Project Structure

Repository Layout

gunn/
├── .github/
│   └── workflows/
│       └── ci.yml          # CI pipeline (lint, type checks, tests, contracts)
├── .kiro/                  # Kiro guidance and specs consumed by the AI agent
│   ├── steering/
│   └── specs/
├── docs/                   # Human-facing documentation (kept in sync with steering docs)
│   ├── product.md
│   ├── structure.md
│   └── tech.md
├── schemas/                # Contract definitions checked in CI
│   ├── README.md
│   ├── openapi.yaml
│   └── proto/
│       └── simulation.proto
├── src/gunn/               # Python package (see layout below)
├── tests/                  # Repository-level tests (integration, performance, contract)
│   ├── contract/
│   ├── integration/
│   ├── performance/
│   └── test_*.py
├── dist/                   # Build artifacts (created by `uv build`, may be absent locally)
├── CODE_OF_CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── README.md
├── SECURITY.md
├── TEST_STATUS.md
├── pyproject.toml          # Project + tool configuration
└── uv.lock                 # Dependency lock file

Source Code Organization (current implementation)

src/gunn/
├── __init__.py             # Public exports (Orchestrator, AgentHandle, etc.)
├── __main__.py             # Allows `python -m gunn`
├── adapters/               # Adapter namespaces (placeholders until tasks 17–19)
│   ├── __init__.py
│   ├── llm/__init__.py
│   ├── unity/__init__.py
│   └── web/__init__.py
├── cli/
│   ├── __init__.py
│   ├── __main__.py
│   └── replay.py           # Deterministic replay CLI (implemented)
├── core/
│   ├── __init__.py
│   ├── event_log.py        # Append-only log with hash chain + concurrency tests
│   └── orchestrator.py     # Orchestrator, AgentHandle, default validator (stubbed logic)
├── facades/
│   └── __init__.py         # Placeholder package for upcoming RL/message facades
├── policies/
│   ├── __init__.py
│   └── observation.py      # Partial observation filtering + JSON Patch deltas
├── schemas/
│   ├── __init__.py
│   ├── messages.py         # Pydantic models (WorldState, View, etc.)
│   └── types.py            # TypedDicts (Intent, Effect, ObservationDelta, CancelToken)
├── storage/
│   ├── __init__.py
│   └── dedup_store.py      # SQLite + in-memory deduplication store
└── utils/
    ├── __init__.py
    ├── errors.py           # Structured error types (StaleContextError, etc.)
    ├── hashing.py          # Hash chain utilities
    ├── hashing_demo.py     # Example usage (dev aid)
    ├── scheduling.py       # Weighted round-robin scheduler
    ├── telemetry.py        # Logging, Prometheus metrics, timers
    └── timing.py           # TimedQueue / monotonic clock helpers (+ demos/tests)

  • Unit tests for core utilities live alongside their modules (test_*.py inside src/gunn/**).

  • Repository-level integration/performance/contract tests are in tests/.

  • Snapshot storage, validation policies, and facade implementations are tracked in tasks.md and not yet present in the tree.

Key Design Principles (still applicable)

  • Schema separation: Contract files live in schemas/; runtime models live in src/gunn/schemas/.

  • Deterministic core: core/orchestrator.py and core/event_log.py enforce ordering and log integrity.

  • Observation policies: policies/observation.py encapsulates filtering/delta logic with configurable limits.

  • Two-phase processing: Orchestrator handles idempotency, quotas, backpressure, fairness, then effect emission.

  • Telemetry: utils/telemetry.py centralises logging + metrics; metrics server start is opt-in via start_metrics_server.

Configuration & Tooling Files

  • pyproject.toml configures Hatchling, uv integration, dependencies, Ruff, MyPy, and Pytest.

  • uv.lock locks dependency versions.

  • .github/workflows/ci.yml runs formatting, linting, typing, tests, and contract drift checks.

  • CI/formatting assumes uv for environment management; local .venv directories are optional and not checked in.

Development Conventions

  • src/ layout with explicit py.typed for type checkers.

  • Strict typing in production code; tests relax some MyPy rules via overrides.

  • Async-first design: orchestration, queues, and stores expose async APIs.

  • Docs and steering guides mirror each other—update docs/ and .kiro/steering/ together.

Import Patterns

# Public API imports
from gunn import Orchestrator, AgentHandle, OrchestratorConfig

# Internal usage examples
from gunn.core.orchestrator import Orchestrator
from gunn.policies.observation import ObservationPolicy
from gunn.schemas.types import Intent, Effect
from gunn.storage.dedup_store import DedupStore
from gunn.utils.telemetry import setup_logging, PerformanceTimer

Open Source Metadata

  • Root documents (LICENSE, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md) stay in sync with GitHub publishing expectations.