{"id":49505183,"url":"https://github.com/arn0ld87/agora","last_synced_at":"2026-05-01T15:01:05.315Z","repository":{"id":353105366,"uuid":"1217186139","full_name":"arn0ld87/agora","owner":"arn0ld87","description":"Self-hosted GraphRAG + multi-agent social-media simulator. Upload a doc → build a knowledge graph → spawn persona-driven agents → generate a report. Ollama \u0026 Neo4j instead of Cloud-APIs. DACH-first. Lokaler Multi-Agent-Social-Media-Simulator mit GraphRAG-Pipeline. Dokument hoch, Knowledge-Graph bauen, Personas spawnen, Report raus. Ollama + Neo4j","archived":false,"fork":false,"pushed_at":"2026-05-01T01:17:41.000Z","size":20694,"stargazers_count":1,"open_issues_count":42,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-01T01:17:52.762Z","etag":null,"topics":["agent-simulation","camel-ai","flask","graphrag","knowledge-graph","local-llm","multi-agent","neo4j","oasis","ollama","self-hosted","social-media-simulation","vue3"],"latest_commit_sha":null,"homepage":"https://alexle135.de/blog","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arn0ld87.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY_REPORT.md","support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-21T16:22:24.000Z","updated_at":"2026-05-01T01:17:46.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arn0ld87/agora","commit_stats":null,"previous_names":["arn0ld87/agora"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/arn0ld87/agora","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arn0ld87%2Fagora","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arn0ld87%2Fagora/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arn0ld87%2Fagora/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arn0ld87%2Fagora/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arn0ld87","download_url":"https://codeload.github.com/arn0ld87/agora/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arn0ld87%2Fagora/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32501403,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-simulation","camel-ai","flask","graphrag","knowledge-graph","local-llm","multi-agent","neo4j","oasis","ollama","self-hosted","social-media-simulation","vue3"],"created_at":"2026-05-01T15:00:40.510Z","updated_at":"2026-05-01T15:01:05.280Z","avatar_url":"https://github.com/arn0ld87.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"./media/logo.png\" alt=\"Agora\" width=\"100%\"/\u003e\n\n# Agora\n\n**Local-first, cloud-compatible Agentic-Prediction-Engine.**\n\nFork von [nikmcfly/MiroFish-Offline](https://github.com/nikmcfly/MiroFish-Offline), basierend auf [MiroFish](https://github.com/666ghj/MiroFish).\n\n\u003e **v0.8.0 released:** [Release Notes](docu/2026-05-01-v0.8.0-release-notes.md) — 13/13 Issues geschlossen, **519 Tests grün** (488 Backend + 31 Frontend). Vorgänger: [v0.7.0](docu/2026-05-01-v0.7.0-release-notes.md).\n\n[![Repository](https://img.shields.io/badge/GitHub-arn0ld87%2Fagora-111?style=flat-square\u0026logo=github)](https://github.com/arn0ld87/agora)\n[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue?style=flat-square)](./LICENSE)\n[![Neo4j](https://img.shields.io/badge/Neo4j-5.18%2B-4581C3?style=flat-square\u0026logo=neo4j\u0026logoColor=white)](https://neo4j.com/)\n[![Ollama](https://img.shields.io/badge/Ollama-local%20or%20cloud-000?style=flat-square)](https://ollama.com/)\n\n[Deutsch](#deutsch) · [English](#english)\n\n\u003c/div\u003e\n\n---\n\n\u003e ## Status: v0.8.0 — released 2026-05-01\n\u003e\n\u003e Agora ist ein aktiver, **experimenteller Fork**. Graph-Build, Simulation und\n\u003e Report-Pipeline können bei ungünstigen Bedingungen (langsame Ollama-Cloud,\n\u003e JSON-Mode-Aussetzer, Modellwechsel) Fehler produzieren.\n\u003e **Nicht öffentlich erreichbar machen.** Die API hat einen optionalen\n\u003e `AGORA_AUTH_TOKEN`-Guard und restriktive CORS-Defaults, ist aber weiterhin\n\u003e für lokale Single-User-Setups gedacht, nicht für Mehrbenutzer- oder\n\u003e Internet-Betrieb.\n\u003e\n\u003e **Getestet aktuell hauptsächlich mit:**\n\u003e - LLM: `qwen3-coder-next:cloud` (Ollama Cloud)\n\u003e - **Embedding: `qwen3-embedding:4b`** (2560-dim, `VECTOR_DIM=2560` nötig)\n\u003e\n\u003e Der frühere Default `nomic-embed-text` (768-dim) funktioniert weiterhin,\n\u003e ist aber nicht mehr der aktiv gepflegte Pfad.\n\u003e\n\u003e **Docker Hub:** `docker pull alexle135/agora-agora:latest` |\n\u003e [GHCR](https://github.com/arn0ld87/agora/pkgs/container/agora)\n\n---\n\n## Deutsch\n\n### Was ist Agora?\n\nAgora ist eine lokale Multi-Agenten-Simulation für öffentliche Reaktionen, Marktstimmung und soziale Dynamiken.\n\nDu lädst ein Dokument hoch, Agora extrahiert daraus einen Wissensgraphen, erzeugt Agenten-Personas mit Rollen, Haltungen und Aktivitätsprofilen, simuliert Diskussionen auf Social-Media-artigen Plattformen und erstellt danach einen Report. Das System läuft lokal mit Neo4j und Ollama, kann aber auch OpenAI-kompatible Cloud-Endpunkte verwenden.\n\n### Engineering-Stand v0.8.0\n\n- **Quality-Gates vorhanden**: `npm run check` führt Backend-Linting (default-strict auf `app/ tests/`), Backend-Tests, Frontend-Lint, Frontend-Tests (Vitest auf `jsdom`) und Frontend-Build aus (**488 Backend + 31 Frontend Tests**, 2 Redis-Integrationstests skippen sauber ohne `TEST_REDIS_URL`).\n- **Design-System konsolidiert (Slice 1)**: `tokens.css` als Source-of-Truth, UI-Komponenten (`Btn`, `Badge`, `Field`, `Card`, `Select`) auf Tokens umgestellt, harte Farbwerte in Views/Layouts durch Token-Referenzen ersetzt.\n- **Persona Review (Slice 2)**: Generierte Personas sind vor Simulationsstart prüfbar, editierbar und freigebbar. Quality-Heuristiken (Dubletten, fehlende Kernfelder, Rollen-Diversität) liefern Badges. `PERSONA_REVIEW_ENABLED=true` blockt Simulationsstart bis alle Personas approved sind.\n- **Run Dashboard (Slice 3)**: Zentrale `/runs`-View mit Status, Datum, Modell, Dokument, Graph-ID, Persona-Anzahl. Detail-Drawer für Fehler, Artefakte und Copy-Buttons. Runs-Persistenz über `RunRegistry`.\n- **Evidence \u0026 Confidence (Slice 4)**: Report-Claims tragen `confidence`-Score und strukturierte `evidence`-Blöcke (Graph-Metriken, Agentenaktionen). UI zeigt Confidence-Badges und Evidence-Drawer.\n- **Export Center (Slice 5)**: JSON- und Markdown-Export für Reports, CSV für Polarisationsmetriken, GraphML für Graphen, SVG/PNG/PDF für Graph-Ansicht.\n- **LLM-Resilienz**: `LLMClient.chat` und `describe_image` retryen über `llm_call_with_retry` auf transiente Upstream-Fehler (`APIConnectionError`, `APITimeoutError`, `RateLimitError`, `APIStatusError` mit 5xx/408/429). Schützt v. a. die Ontology-Generierung gegen Ollama-Cloud-5xx-Hickser.\n- **Event-Bus-Transport (#9 + #17)**: `SimulationEventBus`-Port mit In-Memory-, File- und Redis-Adapter. Redis `7-alpine` wird vom `docker-compose.yml` mitgestartet. Live-Kanäle (`control`/`state`) gehen über Redis Pub/Sub mit retained Snapshot. **Seit Issue #17** laufen auch `rpc.command` / `rpc.response.*` hybrid: Backend published parallel auf Redis und File, `_await_response` race't beide Quellen, der Verlierer wird aufgeräumt. Subprocess-Listener `RedisIPCBridge` (`backend/scripts/subprocess_redis_bridge.py`) sitzt im OASIS-Eventloop neben dem File-Polling. Backout über `EVENT_BUS_BACKEND=file`.\n- **Frontend Push (#9 Phase C)**: `GET /api/simulation/\u003cid\u003e/stream` (SSE) + `useEventStream`-Composable ersetzen das 2,5-s-Status-Polling in der Simulationsansicht.\n- **Temporal Graph (#10)**: RELATION-Kanten tragen `valid_from_round`/`valid_to_round`/`reinforced_count`; `TemporalGraphService` liefert `/api/graph/snapshot/\u003cgid\u003e/\u003cround\u003e` und `/api/graph/diff/\u003cgid\u003e?start_round=..\u0026end_round=..`. Im UI scrubt der **Round-Slider** im `GraphPanel` durch die Zeitachse (Client-side-Filter, kein extra API-Call beim Scrubben).\n- **Polarisations-Metriken (#12)**: `NetworkAnalyticsService` mit Louvain-Communities, Echo-Chamber-Index und Bridge-Agent-Heuristik; API `GET /api/simulation/\u003cid\u003e/metrics`. Dokumentation in `docu/analytics.md`.\n- **Ontology-Mutation (#11, Phase 1+2)**: `OntologyManager` (thread-safe) + `OntologyMutationService` mit Modi `disabled` / `review_only` / `auto`. **NER → Mutation-Wiring ist live**: `Neo4jStorage.add_text` reicht NER-emittierte unbekannte Entity-Types automatisch an den Service weiter; Service-Exceptions blockieren Ingestion nicht.\n- **DI-Container (#14)**: Alle Kern-Services laufen über `AgoraContainer` — keine Service-Locator-Suche mehr in `app.extensions`.\n- **API-Contract-Härtung Richtung v1.0**: zentrale Success-/Error-Envelopes (`success`, `data`, `error`, `code`) werden schrittweise durchgesetzt. Auth-Fehler, rohe `dict`-Returns in `@handle_api_errors` sowie Framework-404/405 unter `/api/*` liefern konsistente JSON-Responses. Laufende Schritte stehen in `docu/v1-development-log.md`.\n- **Workspace-Layout-Shell (EPIC-03)**: `WorkspaceLayout` / `WorkspaceHeader` / `WorkspaceSplit` / `WorkspaceModeSwitch` / `WorkspaceStepStatus` / `WorkspaceBrandLink` (`frontend/src/layouts/`) sind die gemeinsame Shell für alle 5 Pipeline-Views. `useWorkspaceMode` und `useWorkspaceStatus` ersetzen dupliziertes View-Mode/Status-Boilerplate.\n- **GraphPanel modularisiert (EPIC-04)**: `GraphPanel.vue` von 933 auf 98 Zeilen reduziert (−90 %). D3-Renderlogik nach `useGraphRender`-Composable extrahiert (#35), UI in `GraphHints`, `GraphToolbar` und `GraphCanvas` zerlegt (#34).\n- **Polling zentralisiert (EPIC-05)**: Alle 12 `setInterval`-Stellen im Frontend nutzen jetzt das gemeinsame `usePolling`-Composable (#37, #38). SSE-Stream via `useEventStream` ersetzt Status-Polling in der Simulationsansicht (#9, #40).\n- **Simulation-API entmonolithisiert**: Frühere XXL-Datei `backend/app/api/simulation.py` in fokussierte Module zerlegt (10 Dateien, 48 Routen).\n- **Refactoring-Dokumentation liegt im Repo**: Fortschritt, Audit, Zielarchitektur und Roadmap liegen unter `docu/`.\n\n### Was wurde gegenüber MiroFish geändert?\n\n| Bereich | Upstream MiroFish / MiroFish-Offline | Agora |\n|---|---|---|\n| Sprache/UI | Chinesischer Ursprung, später englische Migration | Deutsche UI als Default, Englisch als Fallback |\n| Graph Memory | Zep/Graphiti-Ansatz im Ursprung | Eigene `GraphStorage`-Abstraktion mit Neo4j 5.18+ |\n| LLMs | DashScope/OpenAI-orientiert | Ollama lokal oder beliebiger OpenAI-kompatibler Endpoint |\n| Modelle | Primär per `.env` | Modell-Auswahl im Workflow, plus `.env`-Fallback |\n| Simulation | Feste KI-Personas | Persona-Limit, manuelle Personas, Sprache/Modell pro Vorbereitung |\n| Report | ReportAgent mit Graph-Tools | Report-Modell wechselbar, Tool-Log sichtbar, optional Webtools |\n| Agent-Tool-Use | Nicht stabiler Kernpfad | Experimentell, opt-in, default aus |\n| Region/Zeit | Upstream China-Kontext | DACH / Europe-Berlin Timing-Profil |\n\n### Kernfunktionen\n\n- **GraphRAG-Ingest**: PDF, Markdown oder Text hochladen; Entitäten und Beziehungen landen in Neo4j.\n- **Flexible Ontologie-Generierung**: Entitätstypen sind nicht mehr hart auf exakt 10 begrenzt; Defaults sind 8-16 Typen plus Pflicht-Fallbacks `Person` und `Organization` (`ONTOLOGY_MIN_ENTITY_TYPES`, `ONTOLOGY_MAX_ENTITY_TYPES`).\n- **Modellauswahl im Workflow**: Modell und Agentensprache können bereits auf der Start-/Upload-Seite und in der Umgebungsvorbereitung gewählt werden.\n- **Gefrorene Simulation-Config**: Eine vorbereitete Simulation speichert ihr Modell in `simulation_config.json`; spätere `.env`-Änderungen wirken erst bei neuer Vorbereitung.\n- **Persona-Steuerung**: Agentenanzahl begrenzen, Personas durchsuchen, manuelle Personas hinzufügen oder löschen; erzeugte oder manuelle Personas können in einer lokalen Bibliothek gespeichert und später wiederverwendet werden.\n- **Simulation-Laufsteuerung**: Laufdauer in Tagen und optionales Rundenlimit setzen, Start, Stop, Pause/Resume nach Rundenende und rohes Console-Log der OASIS-Subprozesse.\n- **ReportAgent**: Nutzt Graph-Tools, Interviews und Panorama-Suche; Report-Modell kann beim Generieren/Regenerieren gewechselt werden.\n- **Optionaler Live-Web-Kontext**: Mit `TAVILY_API_KEY` kann der ReportAgent aktuelle externe Fakten recherchieren.\n- **Experimenteller Agent-Tool-Use**: Simulationsagenten können vor einer Aktion den Wissensgraphen abfragen, wenn `ENABLE_AGENT_TOOLS=true` gesetzt ist.\n- **Secret-Guardrail**: Neo4j-Passwörter werden nicht in persistierte Simulation-Artefakte serialisiert.\n\n### Workflow\n\n1. **Upload \u0026 Modellwahl**\n\n   Dokumente hochladen, Fragestellung formulieren, LLM-Modell und Agentensprache wählen.\n\n2. **Graph Build**\n\n   Agora chunked das Dokument, ruft das LLM für NER/Relation-Extraction auf und schreibt Graphdaten nach Neo4j.\n\n3. **Environment Setup**\n\n   Agenten-Personas und Simulationsparameter werden erzeugt. Modell, Sprache, Agentenlimit, Laufdauer und optional gespeicherte Personas werden in der Simulation eingefroren.\n\n4. **Simulation**\n\n   OASIS läuft als Subprozess. Aktionen erscheinen live; Console-Logs helfen beim Debugging. Pause/Resume ist möglich.\n\n5. **Report**\n\n   Der ReportAgent durchsucht Graph und Simulation, kann Agenten interviewen und optional Webtools nutzen. Das Report-Modell ist wechselbar.\n\n6. **Interaction**\n\n   Nach der Simulation kannst du mit Agenten oder dem ReportAgent weiterarbeiten.\n\n### Demo-Teaser\n\n\u003cdiv align=\"center\"\u003e\n\u003ca href=\"./static/media/agora-teaser.mp4\"\u003e\n\u003cimg src=\"./static/media/agora-teaser-preview.gif\" alt=\"Agora Demo-Teaser\" width=\"100%\"/\u003e\n\u003c/a\u003e\n\u003cbr\u003e\n\u003ca href=\"./static/media/agora-teaser.mp4\"\u003eTeaser als MP4 öffnen\u003c/a\u003e\n\u003c/div\u003e\n\n### Schnellstart\n\n#### Voraussetzungen\n\n- Node.js 18+\n- Python 3.11+\n- `uv`\n- Neo4j 5.18+\n- Ollama mit mindestens:\n\n```bash\n# Default-LLM (lokal) oder Cloud-Variante\nollama pull qwen2.5:32b\n# Aktuell genutztes Embedding (2560 dim, erfordert VECTOR_DIM=2560)\nollama pull qwen3-embedding:4b\n# Fallback (768 dim), falls du kein Qwen3-Embedding willst:\n# ollama pull nomic-embed-text\n```\n\n#### Option A: Docker Compose\n\nDocker Compose startet Agora und Neo4j. Ollama läuft standardmäßig auf dem Host und wird aus dem Container über `host.docker.internal` erreicht.\n\n```bash\ngit clone https://github.com/arn0ld87/agora.git\ncd agora\ncp .env.example .env\n\ndocker compose up -d\n```\n\n**Dev-Hinweis:** Das Repo enthält zusätzlich eine `docker-compose.override.yml`, die den Source-Code nach `/app` bind-mountet und `node_modules` / `frontend/node_modules` / `backend/.venv` als named volumes isoliert. Damit greifen Code-Änderungen im laufenden Dev-Container sofort, ohne dass das Image für reine Source-Änderungen neu gebaut werden muss.\n\nNützliche Dev-Kommandos:\n\n```bash\n# Container mit Dev-Override neu erstellen\n\ndocker compose up -d --force-recreate agora\n\n# Wenn Docker-/Dependency-Layer geändert wurden\n\ndocker compose build agora \u0026\u0026 docker compose up -d --force-recreate --no-deps agora\n\n# Wenn named volumes für Dependencies einmal resettet werden sollen\n\ndocker compose down -v \u0026\u0026 docker compose up -d\n```\n\nDanach:\n\n- Frontend: \u003chttp://localhost:5173\u003e\n- Backend Health: \u003chttp://localhost:5001/health\u003e\n- Neo4j Browser: \u003chttp://localhost:7474\u003e\n\n#### Option B: Lokal ohne Docker\n\n```bash\ngit clone https://github.com/arn0ld87/agora.git\ncd agora\ncp .env.example .env\n\nnpm run setup:all\nnpm run dev\n```\n\n### Wichtige Konfiguration\n\nAlle Laufzeitwerte kommen aus `.env`.\n\n```env\n# LLM / Ollama oder OpenAI-kompatibler Endpoint\nLLM_API_KEY=ollama\nLLM_BASE_URL=http://localhost:11434/v1\nLLM_MODEL_NAME=qwen2.5:32b\n\n# Neo4j\nNEO4J_URI=bolt://localhost:7687\nNEO4J_USER=neo4j\nNEO4J_PASSWORD=agora\n\n# Embeddings — aktuell getestet mit Qwen3-Embedding (2560 dim)\nEMBEDDING_MODEL=qwen3-embedding:4b\nEMBEDDING_BASE_URL=http://localhost:11434\nVECTOR_DIM=2560\n# Fallback (768 dim): EMBEDDING_MODEL=nomic-embed-text + VECTOR_DIM=768\n\n# GraphRAG Performance\nGRAPH_CHUNK_SIZE=1500\nGRAPH_CHUNK_OVERLAP=150\nGRAPH_PARALLEL_CHUNKS=4\n\n# Sprache / Region\nAGENT_LANGUAGE=de\nREPORT_LANGUAGE=German\nTIME_PROFILE=dach_default\n\n# Experimentell: Tool-Use innerhalb der Simulation\nENABLE_AGENT_TOOLS=false\nMAX_TOOL_CALLS_PER_ACTION=2\n\n# Optional: Live-Webtools im ReportAgent\n# TAVILY_API_KEY=...\n# ENABLE_WEB_TOOLS=true\n```\n\n### Modellwahl und Modellwechsel\n\n- `LLM_MODEL_NAME` ist nur der Default.\n- Die UI fragt `/api/simulation/available-models` ab und zeigt kuratierte Presets plus lokal verfügbare Ollama-Modelle.\n- Modellwahl auf der Startseite/Step 2 steuert Persona- und Config-Generierung.\n- Eine vorbereitete Simulation nutzt das Modell aus ihrer `simulation_config.json`.\n- Der ReportAgent akzeptiert ebenfalls ein Modell-Override beim Generieren, Regenerieren und Chatten.\n- Wenn du eine bereits vorbereitete Simulation mit einem anderen Modell ausführen willst, bereite sie neu vor.\n\n### Agent-Tool-Use\n\nAgent-Tool-Use ist absichtlich **aus**:\n\n```env\nENABLE_AGENT_TOOLS=false\n```\n\nWenn aktiviert, können Simulationsagenten vor einer Aktion Tools wie Graph-Suche oder Recent-Posts nutzen. Das kann bessere kontextuelle Aktionen erzeugen, erhöht aber Latenz, Kosten und Fehlerfläche. Ohne Neo4j-Credentials fällt die Tool-Schleife sauber auf Standard-`LLMAction` zurück.\n\n### Sicherheit\n\n\u003e **Warnung:** Agora ist explizit für den Betrieb auf `localhost` oder in einem\n\u003e vertrauenswürdigen Netz (Tailscale, Wireguard, internes LAN) gedacht. Der\n\u003e optionale `AGORA_AUTH_TOKEN`-Guard und die CORS-Whitelist reduzieren die\n\u003e Angriffsfläche, ersetzen aber keine echte Mehrbenutzer-Auth. Nicht direkt ins\n\u003e Internet hängen.\n\n- Keine echten Secrets committen.\n- `.env` bleibt lokal.\n- `.env.example` enthält nur Beispielwerte.\n- Neo4j-Passwörter werden nicht in `simulation_config.json` oder andere persistierte Simulation-Artefakte geschrieben.\n- `backend/uploads/` ist nicht versioniert.\n- Siehe [`docu/security-hardening.md`](./docu/security-hardening.md) für die aktuelle Sicherheitsbaseline (Auth-Token, CORS-Whitelist, SSRF-Blocker, Vision- und Label-Caps) sowie [`docu/SECURITY_REVIEW_SUMMARY.md`](./docu/SECURITY_REVIEW_SUMMARY.md) für den historischen Review-Stand.\n\n### Architektur\n\n```text\nFlask API\n  ├─ api/graph.py\n  ├─ api/report.py\n  ├─ api/status.py\n  ├─ api/simulation_common.py\n  ├─ api/simulation_lifecycle.py\n  ├─ api/simulation_prepare.py\n  ├─ api/simulation_profiles.py\n  ├─ api/simulation_run.py\n  ├─ api/simulation_interviews.py\n  ├─ api/simulation_history.py\n  ├─ api/simulation_entities.py\n  ├─ api/simulation_stream.py\n  └─ api/simulation_metrics.py\n        │\n        ▼\nService Layer\n  ├─ GraphBuilderService / TemporalGraphService\n  ├─ SimulationManager / SimulationRunner\n  ├─ OasisProfileGenerator\n  ├─ SimulationConfigGenerator\n  ├─ NetworkAnalyticsService / OntologyMutationService\n  ├─ GraphToolsService / WebTools\n  └─ ReportAgent\n        │\n        ▼\nGraphStorage Interface\n  └─ Neo4jStorage\n       ├─ EmbeddingService\n       ├─ NERExtractor\n       └─ SearchService\n```\n\nOASIS-Simulationen laufen als separate Subprozesse unter `backend/scripts/`. IPC, Pause/Resume und Run-State laufen über den `SimulationEventBus` (Redis Pub/Sub im Compose-Default, File-Polling als Fallback).\n\n### Entwicklung\n\n```bash\nnpm run setup:all\nnpm run dev\nnpm run check\ncd backend \u0026\u0026 uv run pytest\ncd backend \u0026\u0026 uv run python -m compileall app scripts\n```\n\nWeitere Refactoring- und Architekturprotokolle liegen in `docu/`, unter anderem:\n- `docu/p0-arbeitsprotokoll.md`\n- `docu/p0-simulation-api-split-protokoll.md`\n- `docu/p0-graph-panel-modularisierung-protokoll.md`\n- `docu/target-architecture.md`\n\n### Herkunft und Lizenz\n\nAgora ist ein Fork/Derivat von:\n\n- [nikmcfly/MiroFish-Offline](https://github.com/nikmcfly/MiroFish-Offline)\n- upstream: [666ghj/MiroFish](https://github.com/666ghj/MiroFish)\n\nLizenz: AGPL-3.0, siehe [LICENSE](./LICENSE).\n\n---\n\n## English\n\n\u003e **Status: v0.8.0 — released 2026-05-01.** Agora is an active experimental\n\u003e fork. Graph build, simulation, and report pipeline can fail when Ollama is slow,\n\u003e JSON mode misbehaves, or models are switched mid-run. Not production-ready.\n\u003e The HTTP API has an optional `AGORA_AUTH_TOKEN` guard and localhost-locked CORS\n\u003e defaults, but no real multi-user AuthN/AuthZ — run on localhost or inside a\n\u003e trusted network only. Currently exercised with **LLM `qwen3-coder-next:cloud`**\n\u003e and **embedding `qwen3-embedding:4b` (2560 dim, requires `VECTOR_DIM=2560`)**.\n\u003e\n\u003e **Docker Hub:** `docker pull alexle135/agora-agora:latest` |\n\u003e [GHCR](https://github.com/arn0ld87/agora/pkgs/container/agora)\n\n### What is Agora?\n\nAgora is a local-first multi-agent simulation engine for public reaction, market sentiment, and social dynamics.\n\nUpload a document, extract a knowledge graph, generate agent personas, simulate social-media-like interactions, and produce a structured report. Agora runs locally with Neo4j and Ollama by default, but can also use any OpenAI-compatible cloud endpoint.\n\n### Engineering status in v0.8.0\n\n- **Quality gates are in place** via `npm run check` (**488 backend + 31 frontend tests**, Vitest on `jsdom`, 2 Redis integration tests skip cleanly without `TEST_REDIS_URL`).\n- **Design system consolidated (Slice 1)**: `tokens.css` as source of truth, UI components (`Btn`, `Badge`, `Field`, `Card`, `Select`) tokenized, hardcoded colors replaced with token references.\n- **Persona review (Slice 2)**: Generated personas can be inspected, edited, and approved before simulation start. Quality heuristics (duplicates, missing fields, role diversity) provide badges. `PERSONA_REVIEW_ENABLED=true` gates simulation start until all personas are approved.\n- **Run dashboard (Slice 3)**: Central `/runs` view with status, date, model, document, graph ID, persona count. Detail drawer for errors, artifacts, and copy buttons. Run persistence via `RunRegistry`.\n- **Evidence \u0026 confidence (Slice 4)**: Report claims carry `confidence` scores and structured `evidence` blocks (graph metrics, agent actions). UI shows confidence badges and evidence drawer.\n- **Export center (Slice 5)**: JSON and Markdown export for reports, CSV for polarization metrics, GraphML for graphs, SVG/PNG/PDF for graph view.\n- **Event bus transport (#9 + #17)** with a Redis-backed default (`docker-compose.yml` ships `redis:7-alpine`) and file-polling fallback. Live channels (`control` / `state`) ride Redis pub/sub with a retained snapshot. **Since issue #17** RPC channels (`rpc.command` / `rpc.response.*`) are hybrid: the backend publishes to Redis and the file IPC layer in parallel, then races both sources for the response (loser is cleaned up). The OASIS subprocess listener `RedisIPCBridge` (`backend/scripts/subprocess_redis_bridge.py`) lives next to the legacy file polling. Backout via `EVENT_BUS_BACKEND=file`. SSE bridge at `GET /api/simulation/\u003cid\u003e/stream` keeps the frontend off run-state polling.\n- **Temporal graph (#10)**: RELATION edges carry `valid_from_round` / `valid_to_round` / `reinforced_count`; `/api/graph/snapshot/\u003cgid\u003e/\u003cround\u003e` and `/api/graph/diff/\u003cgid\u003e` answer time-travel queries. The **round slider** in `GraphPanel` scrubs through the timeline (client-side filter; no extra API call while scrubbing).\n- **Polarization metrics (#12)**: `GET /api/simulation/\u003cid\u003e/metrics` returns Louvain communities, echo-chamber index and bridge agents via `networkx` (see `docu/analytics.md`).\n- **Dynamic ontology mutation (#11, phase 1+2)** with three modes (`disabled` / `review_only` / `auto`), thread-safe manager, pluggable scorer, audit log. The NER → mutation wiring is live — `Neo4jStorage.add_text` forwards novel entity types automatically; service exceptions never block ingestion.\n- **Hand-rolled DI container (#14)** underpins all of the above — long-lived services live on `AgoraContainer`, no more `app.extensions` service-locator hunt.\n- **API contract hardening toward v1.0**: centralized success/error envelopes (`success`, `data`, `error`, `code`) are being enforced incrementally. Auth failures, raw `dict` returns in `@handle_api_errors`, and framework-level `/api/*` 404/405 responses now use consistent JSON payloads. Ongoing steps are tracked in `docu/v1-development-log.md`.\n- **Workspace layout shell + state composables (EPIC-03)**: `WorkspaceLayout` / `WorkspaceHeader` / `WorkspaceSplit` / `WorkspaceModeSwitch` / `WorkspaceStepStatus` / `WorkspaceBrandLink` (`frontend/src/layouts/`) are the shared shell for all five pipeline views. `useWorkspaceMode` and `useWorkspaceStatus` remove duplicated view-mode and status boilerplate.\n- **GraphPanel modularized (EPIC-04)**: `GraphPanel.vue` shrunk from 933 to 98 lines (−90%). D3 render logic extracted into `useGraphRender` composable (#35), UI split into `GraphHints`, `GraphToolbar` and `GraphCanvas` (#34).\n- **Polling centralized (EPIC-05)**: All 12 `setInterval` sites in the frontend now use the shared `usePolling` composable (#37, #38). SSE stream via `useEventStream` replaces status polling in the simulation view (#9, #40).\n- **The simulation API was decomposed** into focused route modules instead of one giant `simulation.py` file (10 files, 48 routes).\n- **Refactor logs live in `docu/`** so architectural decisions are traceable in-repo.\n\n### Key Features\n\n- **GraphRAG ingest** with Neo4j 5.18+ and Ollama embeddings (`qwen3-embedding:4b` currently exercised, `nomic-embed-text` still supported).\n- **Flexible ontology generation**: entity types are no longer hard-capped at exactly 10; defaults are 8-16 types plus required `Person` and `Organization` fallbacks (`ONTOLOGY_MIN_ENTITY_TYPES`, `ONTOLOGY_MAX_ENTITY_TYPES`).\n- **Model selection in the workflow** for upload/setup and report generation.\n- **Per-simulation frozen config**: prepared simulations keep their selected model and language.\n- **Persona review \u0026 control**: cap agent count, inspect, edit and approve/reject generated personas before simulation start. Quality heuristics flag duplicates, missing fields, and low role diversity. Save reusable persona templates locally.\n- **Run dashboard**: central overview of all runs with status, model, document, and persona counts. Detail drawer for errors and artifacts.\n- **Simulation controls**: configure duration in days plus an optional round limit, start, stop, pause/resume after a round, plus raw subprocess console logs.\n- **ReportAgent** with evidence-backed claims, graph tools, agent interviews, panorama search, model override, and optional Tavily web tools.\n- **Export center**: JSON/Markdown for reports, CSV for polarization metrics, GraphML for graphs, SVG/PNG/PDF for graph view.\n- **Experimental agent tool-use**: simulation agents can query the knowledge graph before acting when explicitly enabled.\n- **DACH defaults**: German UI, German agent language by default, and Europe/Berlin activity timing.\n- **Secret guardrails**: Neo4j passwords are not serialized into simulation config artifacts.\n\n### Quick Start\n\nHost Ollama is expected by default:\n\n```bash\nollama pull qwen2.5:32b\n# Current embedding (2560 dim, requires VECTOR_DIM=2560):\nollama pull qwen3-embedding:4b\n# Alternative 768-dim embedding:\n# ollama pull nomic-embed-text\n\ngit clone https://github.com/arn0ld87/agora.git\ncd agora\ncp .env.example .env\ndocker compose up -d\n```\n\nOpen:\n\n- Frontend: \u003chttp://localhost:5173\u003e\n- Backend health: \u003chttp://localhost:5001/health\u003e\n- Neo4j Browser: \u003chttp://localhost:7474\u003e\n\nLocal development:\n\n```bash\nnpm run setup:all\nnpm run dev\n```\n\n### Configuration Highlights\n\n```env\nLLM_BASE_URL=http://localhost:11434/v1\nLLM_MODEL_NAME=qwen2.5:32b\nNEO4J_URI=bolt://localhost:7687\nEMBEDDING_MODEL=qwen3-embedding:4b\nVECTOR_DIM=2560\n\nAGENT_LANGUAGE=de\nREPORT_LANGUAGE=German\nTIME_PROFILE=dach_default\n\nENABLE_AGENT_TOOLS=false\nMAX_TOOL_CALLS_PER_ACTION=2\n```\n\nOptional web tools for the ReportAgent:\n\n```env\nTAVILY_API_KEY=...\nENABLE_WEB_TOOLS=true\n```\n\n### Model Switching\n\n`LLM_MODEL_NAME` is the default only. The UI lists curated presets and locally installed Ollama models. The selected model is passed into simulation preparation and report generation. Prepared simulations keep their own `llm_model` in `simulation_config.json`, so re-prepare a simulation when you want to run it with another model.\n\n### Agent Tool-Use\n\nAgent tool-use is experimental and disabled by default. When enabled, agents may run a limited number of graph/context tool calls before producing an action. This can improve context but increases latency and LLM usage. If Neo4j credentials are unavailable at runtime, the tool-aware loop fails closed and falls back to standard OASIS `LLMAction`.\n\n### GPU / CPU\n\nAgora erkennt die GPU-Nutzung automatisch via Ollama REST API (`/api/ps`) — es ist kein `nvidia-smi` oder NVIDIA Container Toolkit im Container nötig. Das Backend fragt Ollama direkt nach geladenen Modellen und deren VRAM-Nutzung.\n\n- **GPU aktiv**: `/api/status` zeigt `ollama_uses_gpu: true` mit VRAM-Belegung in GB.\n- **CPU-only**: Wenn Ollama nur Modelle ohne VRAM meldet, zeigt der Status entsprechende Hinweise.\n- **Ollama nicht erreichbar**: Status meldet `ollama_uses_gpu: null`.\n\nFür GPU-Beschleunigung muss Ollama auf dem Host mit GPU-Zugriff laufen. Optional kann der Container via NVIDIA Container Toolkit GPU-Passthrough bekommen (siehe auskommentierte Sektion in `docker-compose.yml`), das ist aber für die reine Ollama-Nutzung auf dem Host nicht nötig.\n\n### Architecture snapshot\n\n```text\nFlask API\n  ├─ api/graph.py\n  ├─ api/report.py\n  ├─ api/status.py\n  ├─ api/simulation_common.py\n  ├─ api/simulation_lifecycle.py\n  ├─ api/simulation_prepare.py\n  ├─ api/simulation_profiles.py\n  ├─ api/simulation_run.py\n  ├─ api/simulation_interviews.py\n  ├─ api/simulation_history.py\n  ├─ api/simulation_entities.py\n  ├─ api/simulation_stream.py\n  └─ api/simulation_metrics.py\n        │\n        ▼\nService Layer (AgoraContainer DI)\n  ├─ GraphBuilderService / TemporalGraphService\n  ├─ SimulationManager / SimulationRunner\n  ├─ NetworkAnalyticsService / OntologyMutationService\n  ├─ ReportAgent / GraphToolsService / WebTools\n  └─ EventBus (Redis | File | InMemory)\n        │\n        ▼\nStorage Layer → Neo4j / Ollama / Redis / OASIS subprocesses\n```\n\n### Development checks\n\n```bash\nnpm run setup:all\nnpm run dev\nnpm run check\ncd backend \u0026\u0026 uv run pytest\n```\n\nDetailed audit and refactor logs are tracked in `docu/`.\n\n### Attribution\n\nAgora is a fork/derivative of [nikmcfly/MiroFish-Offline](https://github.com/nikmcfly/MiroFish-Offline), which itself is based on [666ghj/MiroFish](https://github.com/666ghj/MiroFish). The simulation engine uses [OASIS](https://github.com/camel-ai/oasis) from CAMEL-AI.\n\nLicense: AGPL-3.0. See [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farn0ld87%2Fagora","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farn0ld87%2Fagora","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farn0ld87%2Fagora/lists"}