leanswarm 0.1.0__tar.gz

leanswarm-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Mohith Das
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

leanswarm-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: leanswarm
+Version: 0.1.0
+Summary: Lean Swarm multi-agent prediction and simulation engine
+Author: Mohith Das
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/mohith-das/leanswarm
+Project-URL: Repository, https://github.com/mohith-das/leanswarm.git
+Keywords: agents,forecasting,simulation,llm,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: diskcache<6.0,>=5.6
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: litellm<2.0,>=1.72
+Requires-Dist: networkx<4.0,>=3.3
+Requires-Dist: pydantic<3.0,>=2.8
+Requires-Dist: sentence-transformers<4.0,>=3.0
+Requires-Dist: sqlite-vss>=0.1.2; platform_system != "Windows"
+Requires-Dist: uvicorn<1.0,>=0.30
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: pre-commit>=3.8; extra == "dev"
+Requires-Dist: pytest>=8.3; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+# Lean Swarm
+
+Lean Swarm is a cost-focused multi-agent prediction and simulation engine designed to approximate
+MiroFish-class narrative forecasting with aggressive batching, sparse activation, hybrid state, and
+strict LLM routing guardrails.
+
+## Overview
+
+Given a seed document and a prediction question, Lean Swarm builds a simulated world of agents,
+runs a bounded number of interaction ticks, and returns:
+
+- a structured prediction report
+- a post-simulation world snapshot with agent states and relationship edges
+
+The project is structured for open-source collaboration, MIT licensing, and PyPI publishing from
+day one.
+
+## Quickstart
+
+### Install
+
+```bash
+pip install -e .[dev]
+cp .env.example .env
+```
+
+Optional with `uv`:
+
+```bash
+uv venv
+uv pip install -e .[dev]
+```
+
+### Run
+
+```bash
+lean-swarm smoke
+lean-swarm simulate --seed examples/seed.txt --question "Will public trust rise this quarter?"
+lean-swarm api
+lean-swarm bench
+```
+
+## Architecture
+
+### Core rules
+
+- All model traffic is routed through `engine/llm.py`.
+- Every LLM route and simulation tick is logged.
+- The engine uses Pydantic schemas at every boundary.
+- LLM calls are retried and concurrency-limited with semaphores.
+
+### Phase 1 engine shape
+
+- Tiered model routing with `FLAGSHIP`, `STANDARD`, and `CHEAP` tiers.
+- Batched group actions for active agents.
+- Archetype pooling with 96 archetypes and up to 50 named agents.
+- Hybrid numeric state for mood, energy, attention, and relationships.
+- Event-driven activation with a bounded active fraction per tick.
+- Hierarchical memory slices for working, episodic, and semantic references.
+- Disk-backed action caching via `diskcache`.
+- Early convergence detection on low-delta ticks.
+
+See [docs/architecture.md](docs/architecture.md) for more detail.
+
+## CLI Usage
+
+### Smoke test
+
+```bash
+lean-swarm smoke
+```
+
+### Simulate a scenario
+
+```bash
+lean-swarm simulate \
+  --seed examples/seed.txt \
+  --question "Will the policy announcement improve sentiment?" \
+  --activation-mode lean \
+  --active-agent-fraction 0.25
+```
+
+### Run the API
+
+```bash
+lean-swarm api --host 127.0.0.1 --port 8000
+```
+
+### Run the benchmark harness
+
+```bash
+lean-swarm bench
+```
+
+## API Usage
+
+### Start server
+
+```bash
+lean-swarm api
+```
+
+### Example request
+
+```bash
+curl -X POST http://127.0.0.1:8000/simulate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "seed_document": "A national survey shows mixed views on new policy proposals.",
+    "question": "Will approval improve over the next month?",
+    "rounds": 4
+  }'
+```
+
+## Benchmarks
+
+`lean-swarm bench` runs the same benchmark cases in both `lean` and `naive` activation modes and
+returns a comparison payload with:
+
+- top-level deltas: `cost_ratio_naive_to_lean`, `quality_delta_lean_vs_naive`,
+  `runtime_ratio_naive_to_lean`
+- per-mode outputs under `modes.lean` and `modes.naive` (quality proxy, runtime, cache stats, token
+  and estimated cost totals)
+- `plot_points`: per-case points with `mode`, `score`, `cost_usd`, `runtime_seconds`,
+  `token_total`, and related fields for quality-vs-cost plotting
+
+This lets you compare lean efficiency against naive full activation and plot quality-vs-cost points
+directly from benchmark output without extra transforms.
+
+## Limitations
+
+- The Phase 1 engine uses deterministic mock responses unless live credentials are configured.
+- Semantic memory is scaffolded but not yet backed by a production embedding and retrieval flow.
+- The web client is intentionally minimal at this stage.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for V2 priorities including multi-world simulations, Monte Carlo
+runs, intervention testing, replay UX, plugin architecture, large-scale agent support, and
+hybrid local+cloud routing.
+
+## Contributing
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), pick an issue template
+that matches your contribution track, and open a focused PR.

leanswarm-0.1.0/README.md

@@ -0,0 +1,145 @@
+# Lean Swarm
+
+Lean Swarm is a cost-focused multi-agent prediction and simulation engine designed to approximate
+MiroFish-class narrative forecasting with aggressive batching, sparse activation, hybrid state, and
+strict LLM routing guardrails.
+
+## Overview
+
+Given a seed document and a prediction question, Lean Swarm builds a simulated world of agents,
+runs a bounded number of interaction ticks, and returns:
+
+- a structured prediction report
+- a post-simulation world snapshot with agent states and relationship edges
+
+The project is structured for open-source collaboration, MIT licensing, and PyPI publishing from
+day one.
+
+## Quickstart
+
+### Install
+
+```bash
+pip install -e .[dev]
+cp .env.example .env
+```
+
+Optional with `uv`:
+
+```bash
+uv venv
+uv pip install -e .[dev]
+```
+
+### Run
+
+```bash
+lean-swarm smoke
+lean-swarm simulate --seed examples/seed.txt --question "Will public trust rise this quarter?"
+lean-swarm api
+lean-swarm bench
+```
+
+## Architecture
+
+### Core rules
+
+- All model traffic is routed through `engine/llm.py`.
+- Every LLM route and simulation tick is logged.
+- The engine uses Pydantic schemas at every boundary.
+- LLM calls are retried and concurrency-limited with semaphores.
+
+### Phase 1 engine shape
+
+- Tiered model routing with `FLAGSHIP`, `STANDARD`, and `CHEAP` tiers.
+- Batched group actions for active agents.
+- Archetype pooling with 96 archetypes and up to 50 named agents.
+- Hybrid numeric state for mood, energy, attention, and relationships.
+- Event-driven activation with a bounded active fraction per tick.
+- Hierarchical memory slices for working, episodic, and semantic references.
+- Disk-backed action caching via `diskcache`.
+- Early convergence detection on low-delta ticks.
+
+See [docs/architecture.md](docs/architecture.md) for more detail.
+
+## CLI Usage
+
+### Smoke test
+
+```bash
+lean-swarm smoke
+```
+
+### Simulate a scenario
+
+```bash
+lean-swarm simulate \
+  --seed examples/seed.txt \
+  --question "Will the policy announcement improve sentiment?" \
+  --activation-mode lean \
+  --active-agent-fraction 0.25
+```
+
+### Run the API
+
+```bash
+lean-swarm api --host 127.0.0.1 --port 8000
+```
+
+### Run the benchmark harness
+
+```bash
+lean-swarm bench
+```
+
+## API Usage
+
+### Start server
+
+```bash
+lean-swarm api
+```
+
+### Example request
+
+```bash
+curl -X POST http://127.0.0.1:8000/simulate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "seed_document": "A national survey shows mixed views on new policy proposals.",
+    "question": "Will approval improve over the next month?",
+    "rounds": 4
+  }'
+```
+
+## Benchmarks
+
+`lean-swarm bench` runs the same benchmark cases in both `lean` and `naive` activation modes and
+returns a comparison payload with:
+
+- top-level deltas: `cost_ratio_naive_to_lean`, `quality_delta_lean_vs_naive`,
+  `runtime_ratio_naive_to_lean`
+- per-mode outputs under `modes.lean` and `modes.naive` (quality proxy, runtime, cache stats, token
+  and estimated cost totals)
+- `plot_points`: per-case points with `mode`, `score`, `cost_usd`, `runtime_seconds`,
+  `token_total`, and related fields for quality-vs-cost plotting
+
+This lets you compare lean efficiency against naive full activation and plot quality-vs-cost points
+directly from benchmark output without extra transforms.
+
+## Limitations
+
+- The Phase 1 engine uses deterministic mock responses unless live credentials are configured.
+- Semantic memory is scaffolded but not yet backed by a production embedding and retrieval flow.
+- The web client is intentionally minimal at this stage.
+
+## Roadmap
+
+See [ROADMAP.md](ROADMAP.md) for V2 priorities including multi-world simulations, Monte Carlo
+runs, intervention testing, replay UX, plugin architecture, large-scale agent support, and
+hybrid local+cloud routing.
+
+## Contributing
+
+Contributions are welcome. Start with [CONTRIBUTING.md](CONTRIBUTING.md), pick an issue template
+that matches your contribution track, and open a focused PR.

leanswarm-0.1.0/pyproject.toml

@@ -0,0 +1,77 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "leanswarm"
+version = "0.1.0"
+description = "Lean Swarm multi-agent prediction and simulation engine"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Mohith Das" }]
+keywords = ["agents", "forecasting", "simulation", "llm", "pydantic"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Framework :: FastAPI",
+]
+dependencies = [
+  "diskcache>=5.6,<6.0",
+  "fastapi>=0.115,<1.0",
+  "litellm>=1.72,<2.0",
+  "networkx>=3.3,<4.0",
+  "pydantic>=2.8,<3.0",
+  "sentence-transformers>=3.0,<4.0",
+  "sqlite-vss>=0.1.2; platform_system != 'Windows'",
+  "uvicorn>=0.30,<1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "build>=1.2",
+  "httpx>=0.27",
+  "mypy>=1.11",
+  "pre-commit>=3.8",
+  "pytest>=8.3",
+  "ruff>=0.6",
+  "twine>=5.1",
+]
+
+[project.scripts]
+lean-swarm = "lean_swarm.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/mohith-das/leanswarm"
+Repository = "https://github.com/mohith-das/leanswarm.git"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.11"
+warn_unused_configs = true
+warn_redundant_casts = true
+warn_unused_ignores = true
+strict_optional = true
+check_untyped_defs = true
+disallow_incomplete_defs = true
+disallow_untyped_defs = true
+ignore_missing_imports = true
+packages = ["lean_swarm"]

leanswarm-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

leanswarm-0.1.0/src/lean_swarm/__init__.py

@@ -0,0 +1,6 @@
+"""Lean Swarm package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+

leanswarm-0.1.0/src/lean_swarm/api/__init__.py

@@ -0,0 +1,4 @@
+from .app import create_app
+
+__all__ = ["create_app"]
+

leanswarm-0.1.0/src/lean_swarm/api/app.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+from fastapi import FastAPI
+
+from lean_swarm import __version__
+from lean_swarm.engine.models import SimulationRequest, SimulationResult
+from lean_swarm.engine.simulator import LeanSwarmEngine
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(
+        title="Lean Swarm API",
+        version=__version__,
+        description="HTTP surface for the Lean Swarm simulation engine.",
+    )
+    engine = LeanSwarmEngine()
+
+    @app.get("/healthz")
+    async def healthz() -> dict[str, str]:
+        return {"status": "ok"}
+
+    @app.get("/smoke", response_model=SimulationResult)
+    async def smoke() -> SimulationResult:
+        return await engine.smoke_test()
+
+    @app.post("/simulate", response_model=SimulationResult)
+    async def simulate(request: SimulationRequest) -> SimulationResult:
+        return await engine.simulate(request)
+
+    return app
+

leanswarm-0.1.0/src/lean_swarm/cli.py

@@ -0,0 +1,130 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+from collections.abc import Sequence
+from pathlib import Path
+
+import uvicorn
+
+from lean_swarm.api.app import create_app
+from lean_swarm.engine.config import RuntimeSettings
+from lean_swarm.engine.models import ActivationMode, SimulationRequest
+from lean_swarm.engine.simulator import LeanSwarmEngine
+from lean_swarm.tools.benchmark import run_benchmark
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="lean-swarm", description="Lean Swarm CLI")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    smoke_parser = subparsers.add_parser("smoke", help="Run a deterministic smoke simulation")
+    smoke_parser.set_defaults(handler=handle_smoke)
+
+    simulate_parser = subparsers.add_parser(
+        "simulate", help="Run a simulation from a seed document and prediction question"
+    )
+    simulate_parser.add_argument("--seed", required=True, help="Path to a seed document")
+    simulate_parser.add_argument("--question", required=True, help="Prediction question")
+    simulate_parser.add_argument("--rounds", type=int, default=6, help="Maximum tick count")
+    simulate_parser.add_argument(
+        "--max-agents", type=int, default=24, help="Maximum number of simulated agents"
+    )
+    simulate_parser.add_argument(
+        "--active-agent-fraction",
+        type=float,
+        default=0.2,
+        help="Fraction of agents active on each tick",
+    )
+    simulate_parser.add_argument(
+        "--activation-mode",
+        choices=[mode.value for mode in ActivationMode],
+        default=ActivationMode.LEAN.value,
+        help="Activation strategy for selecting active agents",
+    )
+    simulate_parser.add_argument(
+        "--group-size", type=int, default=5, help="Number of active agents processed per batch"
+    )
+    simulate_parser.add_argument(
+        "--convergence-threshold",
+        type=int,
+        default=2,
+        help="Stable tick streak before ending simulation early",
+    )
+    simulate_parser.add_argument(
+        "--random-seed", type=int, default=7, help="Random seed for deterministic behavior"
+    )
+    simulate_parser.add_argument(
+        "--use-llm",
+        action="store_true",
+        dest="use_llm",
+        default=True,
+        help="Enable live LLM calls when credentials are available",
+    )
+    simulate_parser.add_argument(
+        "--no-use-llm",
+        action="store_false",
+        dest="use_llm",
+        help="Disable live LLM calls and force mock execution",
+    )
+    simulate_parser.set_defaults(handler=handle_simulate)
+
+    api_parser = subparsers.add_parser("api", help="Run the FastAPI server")
+    api_parser.add_argument("--host", default=None, help="API host override")
+    api_parser.add_argument("--port", type=int, default=None, help="API port override")
+    api_parser.set_defaults(handler=handle_api)
+
+    bench_parser = subparsers.add_parser("bench", help="Run the benchmark harness")
+    bench_parser.set_defaults(handler=handle_bench)
+
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    return int(args.handler(args))
+
+
+def handle_smoke(_: argparse.Namespace) -> int:
+    result = asyncio.run(LeanSwarmEngine().smoke_test())
+    print(result.model_dump_json(indent=2))
+    return 0
+
+
+def handle_simulate(args: argparse.Namespace) -> int:
+    seed_path = Path(args.seed)
+    request = SimulationRequest(
+        seed_document=seed_path.read_text(encoding="utf-8"),
+        question=args.question,
+        rounds=args.rounds,
+        max_agents=args.max_agents,
+        active_agent_fraction=args.active_agent_fraction,
+        activation_mode=args.activation_mode,
+        group_size=args.group_size,
+        convergence_threshold=args.convergence_threshold,
+        random_seed=args.random_seed,
+        use_llm=args.use_llm,
+    )
+    result = asyncio.run(LeanSwarmEngine().simulate(request))
+    print(result.model_dump_json(indent=2))
+    return 0
+
+
+def handle_api(args: argparse.Namespace) -> int:
+    settings = RuntimeSettings.from_env()
+    host = args.host or settings.api_host
+    port = args.port or settings.api_port
+    uvicorn.run(create_app(), host=host, port=port)
+    return 0
+
+
+def handle_bench(_: argparse.Namespace) -> int:
+    result = asyncio.run(run_benchmark())
+    print(json.dumps(result, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

leanswarm-0.1.0/src/lean_swarm/engine/__init__.py

@@ -0,0 +1,6 @@
+from .llm import LiteLLMRouter
+from .models import SimulationRequest, SimulationResult
+from .simulator import LeanSwarmEngine
+
+__all__ = ["LeanSwarmEngine", "LiteLLMRouter", "SimulationRequest", "SimulationResult"]
+

leanswarm-0.1.0/src/lean_swarm/engine/config.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+def _env_flag(name: str, default: bool) -> bool:
+    value = os.getenv(name)
+    if value is None:
+        return default
+    return value.strip().lower() in {"1", "true", "yes", "on"}
+
+
+class RuntimeSettings(BaseModel):
+    cache_dir: Path = Field(default=Path(".leanswarm/cache"))
+    log_dir: Path = Field(default=Path(".leanswarm/logs"))
+    dry_run: bool = True
+    max_concurrency: int = 4
+    retry_attempts: int = 3
+    api_host: str = "127.0.0.1"
+    api_port: int = 8000
+    flagship_model: str = "gpt-4.1"
+    standard_model: str = "gpt-4.1-mini"
+    cheap_model: str = "gpt-4.1-nano"
+
+    @classmethod
+    def from_env(cls) -> "RuntimeSettings":
+        return cls(
+            cache_dir=Path(os.getenv("LEANSWARM_CACHE_DIR", ".leanswarm/cache")),
+            log_dir=Path(os.getenv("LEANSWARM_LOG_DIR", ".leanswarm/logs")),
+            dry_run=_env_flag("LEANSWARM_DRY_RUN", True),
+            max_concurrency=int(os.getenv("LEANSWARM_MAX_CONCURRENCY", "4")),
+            retry_attempts=int(os.getenv("LEANSWARM_RETRY_ATTEMPTS", "3")),
+            api_host=os.getenv("LEANSWARM_API_HOST", "127.0.0.1"),
+            api_port=int(os.getenv("LEANSWARM_API_PORT", "8000")),
+            flagship_model=os.getenv("LEANSWARM_FLAGSHIP_MODEL", "gpt-4.1"),
+            standard_model=os.getenv("LEANSWARM_STANDARD_MODEL", "gpt-4.1-mini"),
+            cheap_model=os.getenv("LEANSWARM_CHEAP_MODEL", "gpt-4.1-nano"),
+        )
+
+    def ensure_dirs(self) -> None:
+        self.cache_dir.mkdir(parents=True, exist_ok=True)
+        self.log_dir.mkdir(parents=True, exist_ok=True)
+
+    @property
+    def llm_log_path(self) -> Path:
+        return self.log_dir / "llm_calls.jsonl"
+
+    @property
+    def tick_log_path(self) -> Path:
+        return self.log_dir / "ticks.jsonl"
+