viralix

<div align="center"> <img src="assets/viralix_banner.png" alt="VIRALIX banner" width="800" /> </div> <div align="center"> [](https://discord.gg/KZGme2KQu) [](https://pypi.org/) </div> <div align="center"> <h2><em>Simulate how society responds — before you launch.</em></h2> <p> <strong>VIRALIX</strong> is an open-source swarm intelligence engine for social response prediction. Drop in your scenario profile. Watch simulated public, creator, influencer, brand, academic, and institutional agents react. Get a response forecast, platform dynamics, and actionable strategy artifacts — in minutes. </p> <p> <a href="https://viralix-ai.com/">Website</a> · <a href="https://viralix.ai">Demo</a> · <a href="https://docs.viralix.ai">Docs</a> · <a href="https://discord.gg/KZGme2KQu">Discord</a> · <a href="#quick-start">Quick Start</a> </p> </div> ## Official Website Visit the live VIRALIX website: [https://viralix-ai.com/](https://viralix-ai.com/) VIRALIX is a scenario-driven simulation stack built on multi-agent swarms, GraphRAG retrieval, and synthesis orchestration. It is designed for creators, product teams, brands, policy/comms teams, and AI engineers who need more than one-shot prompting and want testable strategic outputs. The novel part is the closed simulation loop: graph-grounded personas interact, update memory/graph state, and feed a final consensus engine that produces actionable response plans. ## Key Capabilities | Capability | What It Does | Why It Matters | |---|---|---| | Swarm Simulation | Runs multi-role agents (public, creator, influencer, brand, spy, academic, media/moderation-like roles, etc.) over round-based social dynamics | Surfaces narrative risk and society-level reaction before launch | | Agent Sentiment Layer | Classifies each acting agent's sentiment and aggregates by swarm + global mix | Gives consensus/reporting richer social polarity context instead of only action counts | | GraphRAG Context | Builds and retrieves knowledge graph context via Supabase pgvector (strict retrieval path) | Improves consistency and evidence grounding with explicit non-silent telemetry | | Grounded Reporting | Attaches scraped media grounding summary + source references into report artifacts | Keeps strategy outputs attributable and auditable | | Synthesis + PDF Output | Produces virality score, platform ranking, report, and downloadable PDF | Converts analysis into decision-ready artifacts for launch, crisis, policy, and growth workflows | ## Architecture ```mermaid flowchart TD A[Creator Profile Input] --> B[GraphRAG Builder] B --> C[Knowledge Graph] C --> D[Persona Generator] D --> E[Swarm Simulation Engine] E --> F[Social Role Agents\nPublic / Creator / Brand / Influencer] F --> G[Graph Updates + Memory] G --> E E --> H[Synthesis Engine] H --> I[Virality Score + Script + Posting Plan] style A fill:#0F6E56,color:#fff style I fill:#534AB7,color:#fff ``` ## Quick Start ### Mandatory prerequisites - `OPENAI_API_KEY` (required for GraphRAG embeddings/retrieval) - `SUPABASE_URL` and `SUPABASE_SERVICE_ROLE_KEY` - `USE_SUPABASE_GRAPH_RAG=true` - Python 3.11+ - Node.js 18+ ### Nice-to-have (optional integrations) - Apify (`APIFY_API_KEY`) for richer real-world social grounding - Zep (`ZEP_API_KEY`) for persistent memory - Redis (`REDIS_URL`) for concurrency/caching enhancements - Tavily / Scholar / X / Reddit API keys for expanded grounding coverage ```bash git clone https://github.com/yourusername/viralix cd viralix && cp .env.example .env # add OPENAI + SUPABASE credentials npm run setup:all && npm run dev ``` ```bash # Frontend: http://localhost:5173 | Backend API: http://localhost:8000 ``` ## How It Works (5-Phase Pipeline) 1. **Scenario ingest**: campaign/launch/crisis/market-entry profile, region, platforms, and key drivers. 2. **Graph build**: initial entities/relationships extracted and anchored. 3. **Persona + environment init**: simulated actors and social graph seeded. 4. **Swarm rounds**: agents act, generate discourse, and update graph/memory. 5. **Synthesis + report artifacts**: consensus engine returns virality score, swarm intelligence, society-response forecast, grounded summary, and downloadable report payload. ## New in This Iteration - **Academic analyst swarm enabled by default** so "Swarm Intelligence" surfaces an Academic row whenever pre-swarms run. - **Per-agent sentiment aggregation** (dominant sentiment + by-swarm/global distribution) now feeds synthesis and consensus context. - **Media grounding summary + references** are included directly in report payloads for traceable evidence. - **PDF report export endpoint** added so completed simulation sessions can be downloaded as structured reports. - **Frontend report enhancements** include grounding overview, sentiment block, and one-click PDF download. ## Tech Stack        ## Roadmap ### Done - Non-silent retrieval/memory telemetry added to result payload and UI diagnostics - GraphRAG strict-mode and health checks added to backend health surface - Smoke tests added for GraphRAG and memory retrieval paths - Academic analyst swarm surfaced in default simulation analyst set - Per-agent sentiment aggregation integrated into simulation stats + synthesis context - Grounding summary and references integrated into report output - Downloadable PDF generation for completed simulation sessions ### Upcoming - **Real-world response fidelity track** - Calibrate sentiment trajectories against live-platform outcomes (post-launch backtesting loop) - Expand behavior priors for role-specific reactions (media/moderation/regulator/activist escalation patterns) - Add disagreement-aware consensus scoring (polarization, controversy persistence, narrative reversal risk) - Improve temporal realism with event shocks and delayed reaction windows - Cross-memory continuity across runs - Full Zep recall integration (read + write path hardening) - Mobile companion experience - API monetization tier - 1-click deploy templates See full details in [ROADMAP.md](ROADMAP.md). ## Star History [](https://star-history.com/#tapriliando/viralix&Date) ## Acknowledgments - [CAMEL-AI / OASIS](https://github.com/camel-ai/oasis) - [Supabase](https://supabase.com/) - [Zep](https://www.getzep.com/)