Contributing

Biomata Engine is an early-stage open-source project under the Apache 2.0 license. Community contributions — bug reports, new brains, world implementations, protocol clients, and examples — are welcome.

Development setup

git clone https://github.com/smithd36/biomata-engine.git
cd biomata-engine

# Install with dev tools (pytest + mypy)
pip install -e ".[websocket,dev]"

# Verify tests pass
pytest tests/

# Verify types pass
mypy src/

What to contribute

High-value contributions

Not yet

• SaaS integrations or hosted services
• Visual tooling or UI (planned for a later layer)
• Anything requiring Ollama as a hard dependency for core functionality

Plugin architecture

Biomata uses Python Protocol classes as interfaces. To write a plugin, implement the relevant contract from src/contracts/:

The minimal brain implementation:

from src.contracts.action import Intent, ActionSchema
from src.contracts.brain import BrainContext
from src.contracts.world import AgentView

class MyBrain:
    """Deterministic brain that always chooses the first available action."""

    async def decide(
        self,
        agent:       AgentView,
        observation: dict,
        actions:     list[ActionSchema],
        context:     BrainContext,
    ) -> Intent:
        action = actions[0].name if actions else "idle"
        return Intent(action=action, parameters={}, reasoning="first available action")

Wire it into a simulation via YAML:

agents:
  - id: agent_001
    name: Scout
    brain:
      class: my_package.brains.my_brain.MyBrain

Writing tests

Tests live in tests/. Use pytest with pytest-asyncio for async cases.

• Unit tests for contracts and plugins: tests/unit/
• Integration tests for full simulation runs: tests/integration/
• Tests must not require Ollama or any external service

import asyncio
import pytest
from src.engine.simulation import Simulation

async def test_engine_owned_is_deterministic():
    """Same config, same seed → identical outcomes for one tick."""
    sim1 = Simulation.from_config("examples/engine_owned/sim.yaml")
    sim2 = Simulation.from_config("examples/engine_owned/sim.yaml")
    summary1 = await sim1.run_tick()
    summary2 = await sim2.run_tick()
    actions1 = [(r.agent_id, r.intent.action) for r in summary1.agent_results]
    actions2 = [(r.agent_id, r.intent.action) for r in summary2.agent_results]
    assert actions1 == actions2

Submitting a PR

1. Fork the repo and create a branch: git checkout -b feature/my-brain
2. Make your changes. Add tests if adding new behavior.
3. Run pytest tests/ and mypy src/ — both must pass.
4. Open a PR with a clear description of what it does and why.

PRs that include a working example or test case are much easier to merge.

Code style

• Python 3.11+ features are fine (match, tomllib, | type unions)
• Type annotations on all public interfaces
• mypy src/ must pass with no errors
• No comments explaining what the code does — names should do that
• Comments only for non-obvious constraints or protocol-level workarounds

Roadmap

Contributions that align with the planned roadmap are most likely to be merged quickly:

Questions

Open a GitHub Discussion for questions that aren't bug reports. Issues are for bugs and concrete feature requests.

Licensed under Apache 2.0. By contributing, you agree your contributions are licensed under the same terms.