WORK IN PROGRESS - Under construction

Ometeotl : A Python library to build complex multi-agent simulations, wargames, and AI-driven strategies

Create simulated worlds with competitive or cooperative entities using simple class instantiations. Define goals and strategies through clear, standard formats. Train AI agents to act, adapt, and compete in your world. Navigate through a natively built fog of war

Github repo

Ometeotl: An experimental meta-model for complex decisional systems

Ometeotl is an experimental Python library for modeling multi-actor, multi-space, multi-metric strategic decision-making systems. Inspired by game theory, axiomatic systems, and neutral teleological modeling, it aims to simulate complex interactions across hierarchical actors, asymmetric temporalities, and perceptual imperfections.

Cultural Inspiration

The name Ometeotl draws from Aztec mythology, where Ōme means “two” or “dual” in Nahuatl, and teōtl translates to “divinity.” Ometeotl embodies the primordial duality—male (Ometecuhtli) and female (Omecihuatl)—as the supreme creator residing in Omeyocan, the “Place of Duality.” This concept of inherent duality and generative potential mirrors the library’s core philosophy: modeling conflict, cooperation, and emergence from opposing forces in decision spaces.

Use Cases

• Advanced multi-agent simulations
• Wargaming and strategic modeling
• Decision-making benchmarks for symbolic and generative AI
• Game development and interactive systems

Work in Progress

This project is actively under development. The current repository already implements a functional core for modeling, perception, projection, composite and abstract actors, strategy building, server-authoritative runtime control, and a dedicated validation layer. Generation, IO workflows, and end-to-end examples remain in progress.

Current Status

• Functional model core with actors, resources, spaces, world, registry, and spatial graphs.
• Composite actor hierarchies with explicit component links, traversal helpers, and abstract-space support.
• Perception and sensor layers with epistemic statuses and perceived component links.
• Projection and strategy layers with projected successor perceptions and perception-driven strategy chaining.
• Teleology and utility layers with first-class goals, admissibility/feasibility tools, and game utility/ranking primitives.
• Dedicated validation layer with staged validation pipeline, policy profiles (observe_only, enforce_structure, enforce_domain), and diagnostics.
• Authority/runtime boundary in src/ometeotl_core/generic/ for server-owned world mutation flows.
• Current automated baseline: 317 collected tests.

Near-Term TODOs

• Implement dedicated IO workflows.
• Implement contextual generation and repair.
• Extend the game layer beyond current utility/ranking primitives with richer solver-facing abstractions.
• Extend the strategy layer to support one action emitting several alternative projected outcomes, with branch-specific successor perceived states on StrategyOutcomeBranch.
• Add reference examples and end-to-end demo worlds.

Join the Journey

All contributions are welcome! Whether it’s code refinements, axiom suggestions, documentation, testing, or cultural insights into the name’s resonance, your input will shape Ometeotl. Check the specs, README, or CONTRIBUTING.md to get started. Fork, PR, or open an issue—let’s build this together.

Start your first PR and become an Eagle Warrior !

Developer Ranks - The Path of the Serpent

The Path of the Serpent represents knowledge, depth, and commitment.
It is the path of those who learn, refine, and wage a quiet, relentless struggle against bad code—both in the system and within themselves.

	Eagle Warrior Requirement First merged PR In Nahua warrior tradition, the eagle symbolizes courage, ascent, and the honor of proving oneself in action.
	Achcauhtli Requirement 2 to 4 merged PR Achcauhtli evokes a proven war leader, a contributor who has moved beyond initiation and begun to earn standing through repeated service.
	Otomi Requirement 5 to 19 merged PR The Otomi warrior figure represents resilience and battlefield reputation, honoring contributors who have become dependable forces within the project.
	Shorn One Requirement 20+ merged PR The Shorn Ones were elite warriors sworn not to retreat, making this rank a symbol of exceptional discipline, loyalty, and sustained achievement.
	Emperor Requirement Founder and principal Maintainer. The Emperor stands as the sovereign guardian of the Order, embodying stewardship, vision, and the sacred balance at the heart of Ometeotl.

Community Benefactors - The Path of the Undying Sun

The Path of the Undying Sun represents clarity, guidance, and transmission.
It is the path of those who illuminate the way for others and sustain the living flame of knowledge.

	Tlamacazqui - Initiate Requirement Notable contribution to the community Those who begin to carry the light and make their presence felt.
	Tlenamacac - Officiant Requirement Significant contribution to the community Those who sustain the flame and help it grow beyond themselves.
	Quetzalcoatl Priest High priest of the Undying Sun Requirement Decisive contribution to the project or its direction Those whose actions shape the path of others and ensure the light endures.

Donors — The Path of the Temple Offering (available after the first release)

The Path of the Temple offering represents the material commitment to the project. It is the path of those who wish to sustain and amplify its development. Those who walk this this path will support :

• the purchase and maintenance of specific infrastructure
• compensation for those on the path of the serpent, depending on their rank and activity
• production of merch.

Historical note: the Aztecs did not use metallic currency—value was expressed through goods, service, and offerings, a principle that inspires this path.

	Tonalli Seed Those who spark the first motion, bringing initial energy into the system.
	Tlaxtli Contributor Those who give and sustain, turning intent into tangible support.
	Tlatquitl Backer Those who provide the substance that allows ideas to take form and endure.
	Tonalli Flowkeeper Those who maintain the flow, ensuring balance, continuity, and lasting momentum.
	Teyolia Source Those who stand at the origin, empowering the whole system through their presence.