FlySwarm

FlySwarm keeps demo artifacts clearly separate from the real swarm system, while allowing both to share stable contracts and adapters.

Tech stack

Backend, harness, and tests are Python-based; model routing is provider-agnostic via LiteLLM, with both local (ollama) and cloud backends.

Repository layout

• apps/demo-landing/ - landing-page experiment and validation demos
• apps/telegram-bot/ - real Telegram chat product surface
• apps/swarm-orchestrator/ - real scheduler/orchestration runtime
• packages/domain/ - shared business entities and rules
• packages/contracts/ - shared interfaces (LLM/storage/flights/notifier)
• packages/adapters/ - swappable implementations (json/sqlite, ollama/cloud, mock/live APIs)
• packages/shared/ - shared config/logging/observability utilities
• harness/ - autonomous local builder loop and tool registry
• orchestrator/ - skills abstraction layer: discovers, plans, runs and verifies skills
• config/ - committed non-secret routing and environment config
• data/ - local runtime data (git-ignored content)
• docs/ - architecture decisions and experiments

Run the demo landing app

cd apps/demo-landing
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -r backend/requirements.txt
uvicorn backend.main:app --reload

Open http://127.0.0.1:8000

Run tests

API + storage tests

python3 -m pytest -q apps/demo-landing/tests/test_storage.py apps/demo-landing/tests/test_signup_api.py

Full suite (includes browser e2e)

One-time browser install (network required, ~100MB):

python3 -m pip install -r apps/demo-landing/backend/requirements.txt
python3 -m pip install -r apps/demo-landing/backend/requirements-dev.txt
python3 -m playwright install chromium
python3 -m pytest -q apps/demo-landing/tests

Or use the verification scripts:

bash scripts/checks/verify_layer2.sh
bash scripts/checks/verify_layer3.sh

Run the harness

Install harness dependencies:

python3 -m pip install -r harness/requirements.txt

Run a task:

python3 -m harness "Inspect demo-landing tests and summarize coverage" --max-steps 8

Provider/model override examples:

python3 -m harness "Run a short planning loop" --provider openai --model openai/gpt-4o
python3 -m harness "Run a short planning loop" --provider ollama --model ollama_chat/llama3.1

Run the skills orchestrator

Discovers every skill under .claude/skills/, plans which (if any) to use for a goal, runs each as an isolated sub-agent, and verifies each skill's input/output. New skills are picked up automatically — no code changes.

# Preview the plan without executing any skill:
PYTHONPATH=. python3 -m orchestrator "<goal>" --dry-run

# Execute, with a total token budget across planner + verifier + all skills:
PYTHONPATH=. python3 -m orchestrator "<goal>" --token-budget 30000

# Enable a disable-model-invocation skill explicitly, or exclude skills:
PYTHONPATH=. python3 -m orchestrator "<goal>" --only skill-builder
PYTHONPATH=. python3 -m orchestrator "<goal>" --skip grill-me

Configuration notes

• LLM routing is configured in config/models.yaml
• Secrets and runtime overrides live in .env (git-ignored)
• Supported waitlist storage backends in this scope:
  • STORAGE_BACKEND=json with FLYSWARM_EMAILS_FILE override
  • STORAGE_BACKEND=sqlite with FLYSWARM_SQLITE_FILE override
• config/agents.yaml and config/storage.yaml are placeholder templates for later phases

Manual sanity checks

• GET /api/health returns {"status":"ok"}
• Click Try Telegram Demo and verify log progression: Interface -> Orchestrator -> Fetching/API -> Analytics -> Notification
• Submit waitlist form:
  • first submit returns success
  • duplicate submit returns already-on-waitlist
  • records are persisted to selected backend

For the autonomous run write-up and harness metrics, see docs/experiments/layer3_autonomous.md.