🏛️ AGORA
Evidence-oriented stakeholder, risk, and scenario analysis
Documents → Knowledge Graph → Personas → Simulation → auditable report
Demo · What Agora does · Pipeline · Quickstart · Architecture · Current status · Security
[!IMPORTANT]
Agora does not predict human behavior. Personas and simulations are synthetic model outputs. Agora is designed to surface plausible stakeholder reactions, conflicts, assumptions, evidence gaps, and alternative scenarios before decisions are made. It does not replace interviews, user research, expert review, or empirical validation.
Demo
The screenshots and clips below were recorded on 12–13 October 2026 against main@d8ed7370, the code base of 0.9.7. They show a real run through the current interface. The scenario is entirely fictional: a six-month pilot of free Saturday buses in the made-up town of “Lindenhafen”. The input was a single one-page German source document (source-lindenhafen.md). From it, Agora extracted a graph of 28 entities and 30 relations and generated 20 personas. The simulation ran 12 rounds on both platforms and produced 84 actions (46 Twitter, 38 Reddit). No personal profiles or access settings are visible. Waiting time is cut from the clips.
1. Start a run and build the graph
2. Review the personas
3. Follow the simulation
4. Settings
The report for this run was still being generated when these recordings were made, so it is not shown here.
End-to-end recording with report (earlier interface)
What Agora does
Agora is a local-first or controlled-hybrid analysis platform for complex stakeholder and decision scenarios. It turns source material into a knowledge graph, derives reviewable stakeholder personas, runs controlled multi-agent interactions, and produces an evidence-oriented report.
The report does not treat every plausible sentence as a fact. Claims, hypotheses, data gaps, source references, simulation evidence, and degradation states are tracked separately so that readers can inspect where a conclusion came from and where the system is uncertain.
Typical use cases include:
- stakeholder and acceptance analysis,
- pre-mortems and rollout-risk analysis,
- comparison of communication or policy variants,
- product and concept reviews,
- research and teaching around GraphRAG, multi-agent systems, and evidence gating.
Pipeline
flowchart LR
A[Documents / websites] --> B[Knowledge Graph]
B --> C[Stakeholder Personas]
C --> D[Multi-Agent Simulation]
D --> E[Evidence + Claim Gates]
E --> F[Report / Compare / Export]
1. Ingest and graph
Uploaded PDF, Markdown, and text sources are extracted, chunked, embedded, and mapped into Neo4j. Uploaded-file provenance is carried through ingestion and retrieval so report evidence can resolve back to concrete document/chunk anchors (ADR-0013).
2. Generate and review personas
Candidate entities pass type filtering, deduplication, eligibility checks, persona-kind rules, and identity alignment before profiles are created. Personas can be reviewed and edited before simulation.
3. Run the simulation
OASIS/CAMEL runs in a separate subprocess. Redis transports live state and events between the simulation runtime and the web application. A user stop is represented explicitly rather than being disguised as a crash.
4. Generate the report
The report pipeline plans sections, queries graph and simulation evidence, can interview personas again, extracts claims, binds evidence, verifies quantitative prose, and records degradations. Structurally incomplete or cancelled reports are marked INCOMPLETE rather than normal COMPLETED.
5. Compare and export
Reports and runs can be inspected, compared, and exported. Contract-invalid evidence is withheld or represented as evidence_omitted instead of being shipped as if it had passed validation.
Provider and model routing
Agora separates provider definitions, connections, secrets, model references, and per-stage routes.
Supported transport classes are:
| Transport | Meaning | Example |
|---|
http | remote or local HTTP API | OpenAI, Gemini, MiniMax, Amazon Bedrock (Mantle; also Claude). Anthropic: model discovery only, native chat is rejected (#1284) |
local | local HTTP service without API-key auth | Ollama |
cli | local authenticated CLI subprocess | Codex CLI, Claude Code CLI |
codex_cli (ChatGPT subscription) is a first-class session transport: no HTTP base URL and no API key are expected. claude_cli (Claude subscription, #1531) runs the local Claude Code CLI in a subprocess with an isolated HOME per call and authenticates via a long-lived claude setup-token (CLAUDE_CODE_OAUTH_TOKEN) held in the encrypted secret store. Amazon Bedrock (#1282) talks the OpenAI-compatible Bedrock Mantle endpoint (region eu-central-1 by default) via a bearer API key, not boto3/SigV4. See docs/provider-runtime-settings.md for the current routing model.
Embedding configuration is intentionally separate from chat routing. Read/write paths resolve their index and property names canonically through the store; migration activates a new index version only after verified re-embedding and an index check. #1417 is closed: operational dimensions, the legacy bootstrap view, the frontend building mirror, Env/store divergence warnings and pre-write dimension checks are implemented. A real model-switch drill against the production Neo4j and embedding backend remains an operational verification item in #1592.
Architecture
graph TD
UI[Vue 3 + TypeScript + Vite + Pinia] <-->|REST / SSE| API[Flask + Pydantic v2]
API --> ROUTE[LLM Routing + Provider Registry]
ROUTE --> HTTP[HTTP Providers]
ROUTE --> LOCAL[Local Ollama]
ROUTE --> CLI[CLI Providers]
API --> NEO[(Neo4j)]
API --> REDIS[(Redis)]
API --> OASIS[OASIS / CAMEL subprocess]
OASIS --> REDIS
OASIS --> NEO
API --> REPORT[Evidence / Report Pipeline]
| Area | Technology / responsibility |
|---|
| Frontend | Vue 3, TypeScript, Vite, Pinia, Zod |
| Backend | Flask, Python 3.14, Pydantic v2, uv |
| Contracts | Pydantic → generated JSON schemas → Zod mirrors |
| Knowledge graph | Neo4j 5.18+ |
| Event / live state | Redis 8 |
| Simulation | OASIS / CAMEL in a separate subprocess |
| LLM layer | ProviderConnection, AiRoute/LlmRoute, LLMClient |
| Report | evidence collection, claim gates, degradation model, exports |
Production Gunicorn intentionally runs with one web worker while process-local job/monitor state still exists — quantified in ADR-0015: the non-relocatable part is OS-level handles (Popen objects, in-process queues, open file descriptors) inside SimulationRunner, which only a persisted job queue with dedicated workers (#1472) can move. Increasing the worker count is not a harmless performance setting.
A SQLAlchemy/Alembic-backed PostgreSQL layer exists alongside the file/JSON/SQLite stores (self-hosted Supabase is an optional Compose overlay). Repository adapters cover project, simulation, job, report, and LLM profile metadata; the optional workspace path has a PostgreSQL-only adapter. Each migrated metadata store keeps its file/SQLite default and has its own AGORA_*_BACKEND setting. Provider secrets remain in the file-backed Fernet store, and project documents, simulation artifacts, and report contents remain files. The shipped default does not require PostgreSQL; the adapter and activation details are in docs/STATUS.md.
One caveat that the opt-in hides: with the default SqliteLlmProfileRepository, profile API keys are stored in plaintext in the api_key column of instance/llm_profiles.db (backend/app/services/llm_profiles_store.py). Only the Postgres adapter keeps them in the Fernet-backed LlmProfileSecretsStore. Treat that file as a secret.
For the actual architecture and its remaining debts, see docs/architecture.md and docs/STATUS.md.
Quickstart
Requirements
- Git
- Linux or macOS recommended
- Bun >= 1.3 and Node.js
^22.12.0 || ^24.0.0 || >=26.0.0 — the range required by vitest 5 and enforced by install.sh; Node 23 and 25 are intentionally excluded
uv- a configured LLM provider and embedding setup
- Docker for the full-stack container path
Local setup
git clone https://github.com/arn0ld87/agora.git
cd agora
./install.sh
install.sh creates .env from the template and generates the four application secrets that can be generated locally:
SECRET_KEYAGORA_AUTH_TOKENAGORA_SECRET_KEYAGORA_FERNET_KEY
Configure NEO4J_PASSWORD/Neo4j connection details as required and add or activate the desired LLM/embedding provider. Then start the development stack:
bun run dev
Docker setup
./install.sh --docker
Default service endpoints:
| Service | Address |
|---|
| Frontend | http://localhost:5173 |
| Backend | http://localhost:5001 |
| Liveness | http://localhost:5001/health |
| Readiness / diagnostics | http://localhost:5001/api/status |
| Neo4j Browser | http://localhost:7474 in development setups where the port is exposed |
[!WARNING]
Agora is a single-user Stability Beta. Do not expose the development stack directly to the public internet. Use the hardened deployment guidance, TLS/VPN/reverse-proxy controls, and authentication described under docs/deployment-prod-like.md.
Configuration
install.sh prepares the local .env from .env.example; .env.docker.example documents the container settings. Set credentials locally and keep .env out of Git.
| Setting | Purpose |
|---|
SECRET_KEY, AGORA_AUTH_TOKEN, AGORA_SECRET_KEY, AGORA_FERNET_KEY | Application signing, master access, and encrypted stores; generated by install.sh. |
NEO4J_PASSWORD, NEO4J_URI, REDIS_URL | Graph and live-state connections; adjust them for services outside the default Compose network. |
LLM_API_KEY, LLM_BASE_URL, LLM_MODEL_NAME | Initial HTTP-provider settings; provider routes can also be configured in the application. |
EMBEDDING_MODEL, EMBEDDING_BASE_URL, VECTOR_DIM | Embedding model and vector-index settings; keep the dimension consistent with the selected model. |
AGORA_*_BACKEND, DATABASE_URL | Optional PostgreSQL metadata adapters; run Alembic migrations before switching a store. |
Provider setup and route persistence are described in docs/provider-runtime-settings.md. For the optional PostgreSQL path, follow the upgrade runbook (steps, order and rollback per release jump) and the LLM-profile migration runbook; changing a backend setting alone does not migrate existing data.
Development and checks
From the repository root, bun run backend starts only Flask and bun run frontend starts only Vite. The scripts below match the checked-in package configuration:
bun run test:backend # backend pytest suite
bun run test:frontend # frontend Vitest suite
bun run lint:backend # Ruff
bun run lint:frontend # ESLint
cd frontend && bun run typecheck # Vue/TypeScript
Run bun run build for the frontend production build. The pre-push gate documents the scope-specific contract, schema, lint, typecheck, and test checks used before a PR push. PostgreSQL schema migrations, when that optional backend is enabled, run from backend/ with uv run alembic -c migrations/alembic.ini upgrade head.
Repository layout
| Path | Contents |
|---|
backend/ | Flask API, Pydantic contracts, services, migrations, and Python tests. |
frontend/ | Vue application, Zod contract mirrors, and frontend tests. |
schemas/ | Generated contract schemas shared with the frontend. |
docs/ | Current architecture, operations, API references, decisions, and historical research. |
scripts/, deploy/, supabase/ | Quality/development scripts and optional deployment infrastructure. |
Current status
Current product version: 0.9.9 Stability Beta, released on 29 October 2026. It is a patch release on top of 0.9.8 and not 0.10.0. Neither the v0.9.7 nor the v0.9.8 tag shipped container images or release assets: v0.9.7 failed on a CI-only issue, and v0.9.8 (tagged late, on 29 October) failed the image security scan because fixable HIGH vulnerabilities had been published for bundled Python packages in the meantime. 0.9.9 ships the updated packages, the images and the release assets, plus all changes merged since 0.9.8. The release notes for 0.9.9, 0.9.8 and 0.9.7 and CHANGELOG.md list the changes. The next planned cut is still 0.10.0-rc.1.
The exact verified state, recent test evidence, known gaps, and current baseline are maintained in docs/STATUS.md. Release priorities and 0.10/1.0 gates are maintained in ROADMAP.md. This README deliberately avoids embedding fast-aging test counters.
Since 0.9.6, these items have been closed:
- recovery for Prepare, Report, and Graph jobs (#1472),
- the embedding runtime SSoT, alias/entity handling, role-leakage marking, quantifier gates, and manifest/replay fixes,
- file-artifact versioning (#1663) and the compatibility policy (#1664),
- release checksums (#1661) and test isolation (#1632),
- the backend and frontend coverage ratchets (#1671, #1672).
All eight stages of the frontend rebuild (#1790) are on main. The operational rest of that epic is still open. Closed tickets do not establish empirical product validity, and their remaining limits are documented in docs/STATUS.md.
The remaining release work is concentrated on:
- the exception register for the Supabase image scan (#1670),
- clean evaluation fixtures and a documented counter-run (#1240),
- formal cutover and fresh-host install/restore evidence (#1592, #766),
- the AURORA comparison against single-prompt and static-persona baselines and visible product limits (#1662, #1674). The full calibration suite #765 is scheduled after 1.0.
Reproducibility boundary
#1274 is closed. Manifests capture prompt templates, input hashes where available and strict route snapshots; replay preserves the original simulation parameters, permits a model-route override and records deviations. Unrecoverable legacy values remain null, and incomplete legacy manifests can be rejected. By the maintainer decision of 26 September 2026, random_seed is deliberately null; end-to-end RNG wiring was rejected rather than claimed as unfinished release work. Replay does not guarantee identical model outputs or the same experiment result. The boundary is traceable inputs and configuration, not deterministic simulation.
Reference run
The most recent documented visual end-to-end showcase with a report is Reference run 8: Geburtshilfe Hollerau. It follows a fictional public-sector scenario through Graph Build, simulation and live feed, and report. It was recorded before the frontend rebuild. The demo above shows the current interface.
For Report-/Trust-pipeline regression work, Reference run 7: AURORA with Red-Team review remains the technical reference. Run 8 deliberately does not hide its degradations: its exported ReportV3 contains 2 validated claims, 31 hypotheses, 6 data gaps, and five sections that failed generation because of LLM errors.
Reference-run index
Security
Current security foundations include:
- master-token and scoped workspace API-key authentication,
- signed short-lived tickets for browser URL-auth cases such as SSE/downloads,
- encrypted provider-secret and workspace-API-key stores,
- transport checks for credential-bearing HTTP endpoints,
- loopback-oriented production defaults and hardened Compose overrides,
- dependency scanning and an explicit dependency-risk register.
Prompt injection from untrusted model observations/source material is partially hardened: the single-platform tool loop wraps and neutralizes it (#1224), the parallel simulation path and fallback rounds using native CAMEL LLMAction() do not.
See SECURITY.md, docs/auth.md, docs/security-threat-model.md, and docs/dependency-risk-register.md.
Documentation
License and origin
Agora is open source under the AGPL-3.0 license. It descends from MiroFish by way of MiroFish-Offline by Nik (GitHub: nikmcfly), which replaced Zep Cloud with Neo4j and Ollama in March 2026, and has been developed independently under the name Agora since April 2026. See NOTICE for attribution details.
Parts of the simulation runtime use the CAMEL-AI/OASIS ecosystem.
