Product Overview

gunn (群) is a multi-agent simulation core that provides a controlled interface for agent–environment interaction, supporting both single and multi-agent settings.

Core Purpose

The system enables multiple AI agents to interact in a shared environment with:

• Partial observation driven by configurable policies

• Concurrent execution managed by a deterministic orchestrator

• Interruption-aware scheduling with cancel tokens and staleness checks

• An event-driven architecture with a replayable log for auditability

Current Capabilities (implementation status)

• Deterministic event log with hash-chain integrity and a replay CLI for debugging/replay workflows.

• Async orchestrator that handles agent registration, intent submission, deduplication, quota/backpressure enforcement, and weighted round-robin scheduling before emitting effects.

• Observation pipeline that generates RFC6902 JSON Patch deltas per agent, supports latency models, and tracks per-agent view sequences.

• Telemetry utilities providing structured logging with PII redaction plus Prometheus-ready metrics/timers.

• Storage layer with SQLite-backed or in-memory deduplication to guarantee idempotent intent processing.

Roadmap Highlights (see tasks.md)

• Implement richer EffectValidator logic (Task 6) covering permissions, quotas, and conflict resolution.

• Ship RL-style and message-oriented facades (Tasks 13–14) to expose the core through ergonomic APIs.

• Build production adapters (Tasks 17–19) for web, LLM streaming, and Unity integrations.

• Extend observability, performance monitoring, and memory management (Tasks 15–16).

• Harden security, multitenancy, and deployment tooling (Tasks 21–22) ahead of public release.

Target Use Cases

Current builds are best suited for prototyping deterministic multi-agent worlds, experimenting with observation policies, and validating orchestration workflows. Full external adapter support, streaming UX, and end-to-end demos are in progress and tracked via the roadmap above.