---

⚡ Live CWIR Pipeline

Four specialized agents run in sequence. The Fact Checker scores every claim. If confidence is too low, CWIR identifies the single weakest upstream agent and re-runs only from that point — never from scratch. The final score is the harmonic mean of all four agents, so one bad agent pulls the entire score down and forces revision.

---

🗂 What You Can Do

📄 Document Intelligence Upload documents into isolated workspaces. Each file is sentence-chunked (2048-char target, 256-char overlap), embedded with nomic-embed-text, and indexed in pgvector with an HNSW index for sub-10ms retrieval at scale.

🔬 AI Research Engine Ask any question. The 4-agent CWIR pipeline decomposes it, validates sources against your documents, synthesizes a cited answer, and fact-checks every claim — with live WebSocket streaming of each agent's progress.

🕸 Knowledge Graph Every research session extracts entity→relation→entity triples and upserts them into a persistent knowledge graph. Confidence accumulates across sessions. Explore it interactively with draggable nodes, confidence filtering, and entity detail panels.

---

🏗 Architecture

╔══════════════════════════════════════════════════════════════════╗
║                    React 19  +  TypeScript  +  Vite             ║
║  ┌───────────┐  ┌──────────────────┐  ┌────────────────────┐   ║
║  │ Research  │  │  Pipeline (Live  │  │   Graph Explorer   │   ║
║  │   Tab     │  │  DAG animation)  │  │  (force-directed)  │   ║
║  └───────────┘  └──────────────────┘  └────────────────────┘   ║
╚══════════════════════╤═══════════════════════════════════════════╝
                       │  REST + WebSocket
╔══════════════════════▼═══════════════════════════════════════════╗
║                    FastAPI  (asyncpg pool)                       ║
║  ┌─────────────────────────────────────────────────────────┐    ║
║  │              CWIR Pipeline Orchestrator                 │    ║
║  │  QueryAnalyst → SourceValidator → Synthesizer → FC      │    ║
║  │       ↑_______ backward refinement arc ________________│    ║
║  └─────────────────────────────────────────────────────────┘    ║
║  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  ║
║  │  LLM Router  │  │  Hybrid RAG  │  │  KG Upsert Engine    │  ║
║  │  Ollama →    │  │  pgvector +  │  │  ON CONFLICT UPDATE  │  ║
║  │  Claude API  │  │  tsvector    │  │  GREATEST(conf)      │  ║
║  └──────────────┘  └──────────────┘  └──────────────────────┘  ║
╚══════════╤═════════════════════╤════════════════════════════════╝
           │                     │
  ┌────────▼────────┐   ┌────────▼──────────────────────────────┐
  │  Ollama Server  │   │  PostgreSQL 16 + pgvector              │
  │  gemma3:4b      │   │  ┌─────────────────────────────────┐  │
  │  nomic-embed    │   │  │ chunks(vector(768)) HNSW index  │  │
  └─────────────────┘   │  │ chunks(tsvector) GIN index      │  │
                        │  │ knowledge_edges  UNIQUE index   │  │
                        │  │ research_tasks   JSONB results  │  │
                        │  └─────────────────────────────────┘  │
                        └───────────────────────────────────────┘

---

🧠 The CWIR Algorithm

# Confidence-Weighted Iterative Refinement def run_cwir(query, max_depth=2): state = forward_pass(ALL_AGENTS) # 1st pass for depth in range(max_depth): fc = state["fact_checker"] if fc.verdict != "needs_revision": break # done ✓ # Find weakest non-FC agent weakest = argmin([qa, sv, syn]) # Re-run ONLY from weakest node state = forward_pass( agents[weakest:], # O(k) not O(n) state ) # Harmonic mean — one weak agent → low final score return harmonic_mean(qa, sv, syn, fc)

Why harmonic mean? The harmonic mean is bounded above by its minimum value. A single agent scoring 0.10 confidence caps the final score near 0.10, regardless of the other three scores being perfect. Agent scores Arithmetic Harmonic 0.95, 0.90, 0.92, 0.88 0.91 0.91 0.95, 0.90, 0.92, 0.10 0.72 0.31 The second row forces a revision. This is by design — the system should never report high confidence when one agent failed.

---

✨ Feature Highlights

Feature	Description
🎨 Animated DAG Canvas	Live pipeline visualization using raw Canvas 2D API. Agent nodes pulse while running, CWIR revision arcs draw as dashed amber beziers
🕸 Force-Directed KG	Verlet spring simulation (350 iterations) renders a draggable knowledge graph. Click any node for entity detail: all incoming/outgoing edges with confidence
📡 Live WebSocket Streaming	Agent traces stream in real-time as each agent completes. Frontend state machine transitions idle → running → complete
🔍 Hybrid RAG	0.7 × cosine_similarity(pgvector HNSW) + 0.3 × BM25(tsvector) merged in Python for precision + recall balance
🛡 Agent Resilience	Every agent runs inside asyncio.wait_for() with timeout. Crashes and timeouts produce confidence=0.1 degraded output — pipeline always completes
📊 Workspace Stats	Live stat chips: documents, chunks, queries, avg confidence, entity count, KG edge count
🔁 Smart Retry	Exponential backoff on both Ollama and Claude API paths. TTL-cached health probe avoids repeated Ollama checks
🚦 Rate Limiting	Sliding-window per-IP limiter (20 req/min) as a FastAPI Depends — no external Redis needed

---

🗃 Project Structure

ResearchOS/
├── 🐳 docker-compose.yml        PostgreSQL 16 + pgvector
├── ⚙️  Makefile                  up / dev / migrate / test
├── 🔒 .env.example
│
├── backend/
│   ├── 🚀 main.py               FastAPI app — 15 routes + WS endpoint
│   ├── 🧠 pipeline/cwir.py      CWIR orchestrator + backward propagation
│   ├── agents/
│   │   ├── base.py              timeout + error wrapping (asyncio.wait_for)
│   │   ├── query_analyst.py     query decomposition + clarity scoring
│   │   ├── source_validator.py  RAG retrieval + confidence blending
│   │   ├── synthesizer.py       chunk-grounded synthesis + KG extraction
│   │   └── fact_checker.py      claim verification + revision trigger
│   ├── rag/
│   │   ├── chunk.py             NLTK sentence-boundary chunker
│   │   ├── embed.py             Ollama embedding calls
│   │   ├── search.py            hybrid cosine+BM25 search
│   │   └── ingest.py            document → chunks → vectors
│   └── tests/
│       ├── test_agents.py       all 4 agents, JSON fences, fallbacks
│       ├── test_resilience.py   timeout, crash, retry, rate limit
│       ├── test_rag.py          chunking, hybrid search
│       └── test_cwir.py         full pipeline, CWIR loop, harmonic mean
│
└── frontend/src/
    ├── App.tsx                  4-tab routing + workspace state
    ├── api.ts                   typed REST + WebSocket client
    ├── hooks/useResearch.ts     WS lifecycle, phase state machine
    └── components/
        ├── 🎨 DAGCanvas.tsx     animated pipeline (Canvas 2D)
        ├── 🕸 KnowledgeGraph.tsx force-directed KG (Canvas 2D)
        ├── 🔭 GraphExplorer.tsx  full-page KG tab with analytics
        ├── 📊 WorkspaceStats.tsx stat chip bar
        └── 📜 ResearchHistory.tsx past queries list

---

🚀 Quick Start

# 1. Clone & start the database
git clone https://github.com/devhemanthac-commits/ResearchOS -b master
cd ResearchOS
docker compose up -d

# 2. Backend
cp .env.example .env         # add ANTHROPIC_API_KEY
pip install -r backend/requirements.txt
python -c "import asyncio; from backend.database import init_db; asyncio.run(init_db())"
uvicorn backend.main:app --reload --port 8000

# 3. Frontend
cd frontend && npm install
echo "VITE_API_URL=http://localhost:8000" > .env.local
npm run dev                  # → http://localhost:5173

# 4. Pull models
ollama pull gemma3:4b
ollama pull nomic-embed-text

Full setup guide, environment variables, and API reference in the master branch README

---

📦 Source Code

Path	Contents
backend/	FastAPI app, CWIR pipeline, all 4 agents, RAG engine
backend/agents/	QueryAnalyst, SourceValidator, Synthesizer, FactChecker
backend/pipeline/	CWIR orchestrator with backward propagation
backend/rag/	Chunker, embedder, hybrid search
backend/tests/	Full test suite (agents, resilience, RAG, CWIR)
frontend/src/components/	All React components including Canvas 2D visualizations
frontend/src/hooks/	useResearch (WebSocket), useWorkspaces

---