akshara-a

The Autonomous 100% local CLI Agent That Codes While You Sleep This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine Night Ghost 👻: The Autonomous Agent That Codes While You Sleep > "I stopped halfway" → "I woke up further ahead." --- What I Built Every developer and indie hacker knows the evening exhaustion of leaving code half-finished. You hit a wall at 11 PM: functions lack edge-case tests, helper logic is duplicated, and your working tree is messy. By the time you wake up the next morning, context and momentum have vanished. The first hour of your day is spent re-orienting: "Where was I? What broke? What was I about to test?" Night Ghost is an open-source, 100% local CLI agent powered by Ollama designed to bridge that evening-to-morning gap. It is quite literally a benevolent ghost in your machine: - 100% Local & Offline: All inference runs directly on your machine through Ollama. No source code, diffs, or credentials ever leave your device. - Air-Gapped Egress: The test runner actively blocks network access during test runs. - Deterministic Guardrails: Security and path boundaries are enforced in Python code, not by trusting system prompts. 1. In the Evening: You drop a quick task note before closing your laptop: nightghost note "Add unit tests for charge() edge cases and clean up duplicated currency rounding" nightghost sleep 2. Overnight (While You Sleep): Night Ghost wakes up (triggered via local cron/timer), reads your note and recent diffs, creates an isolated branch (nightghost/YYYY-MM-DD), and runs an autonomous, test-gated pipeline: - Plans small, verification-gated steps. - Proposes test additions and safe, behavior-preserving cleanups. - Evaluates every write against strict security guardrails in Python code. - Runs your test suite (pytest) in a sandboxed, offline environment. - Commits every verified step (ghost: <step>). If any test regresses, it automatically rolls back. - Compiles a transparent morning report from measured execution logs. 3. In the Morning: You open your laptop, review the factual report and the clean diff, and decide whether to merge or discard: nightghost report git diff main..nightghost/2026-11-01 --- Demo 1. Terminal Workflow (Local CLI) Watch Night Ghost wake up, analyze the task, run tests, and commit progress autonomously: $ cd demo_project $ nightghost status ┌────────────────────────────────┬──────────────────────┐ │ Property │ Value │ ├────────────────────────────────┼──────────────────────┤ │ Current Git Branch │ main │ │ Uncommitted Changes │ Clean │ │ Scheduled Time │ 01:00 │ │ Configured Model │ gemma4:e2b (ollama) │ │ Test Command │ pytest -q │ │ Ollama Server │ Online │ │ Model Status │ Ready (Installed) │ │ Kill Switch (.nightghost/STOP) │ Disengaged (Ready) │ └────────────────────────────────┴──────────────────────┘ $ nightghost note "Add comprehensive unit tests for payment edge cases" $ nightghost run ┌────────── Overnight Run ──────────┐ │ Night Ghost Active │ │ Model: gemma4:e2b (ollama) │ │ Mode: LIVE RUN │ └───────────────────────────────────┘ [OK] Pipeline completed! Branch: nightghost/2026-10-31 Steps Planned: 2 Steps Executed: 2 Elapsed: 142.7s $ nightghost report 2. Sample Morning Report Output Every claim in the morning report is compiled directly from actions.jsonl and git diff stats—not model hallucinations: # Night Ghost Report: 2026-10-31 Task: "Add comprehensive unit tests for charge() and refund() edge cases" Branch: nightghost/2026-10-31 (2 commits, 2 files, +38 / -6) Model: gemma4:e2b (local) | Runtime: 2m 22s ## Result at a glance [PASS] Tests: 2 -> 6 passing (0 failing) ## What I did 1. Added unit tests for charge() negative amounts raising ValueError: commit a1f4d92 2. Added unit tests for refund() invalid transaction IDs: commit 8c2b1e4 ## Needs your judgment - None. All committed changes are self-contained and behavior-preserving. ## Skipped / failed - None. All attempted steps passed validation. ## Blocked by guardrails - None. All file and command requests adhered to security rules. ## How to review git diff main..nightghost/2026-10-31 nightghost discard # to throw it all away 3. Dry-Run Simulation Mode Night Ghost also provides a simulation mode so you can preview planned steps and check baseline tests without writing files or making commits: nightghost run --dry-run nightghost report --- !Image description Code - GitHub Repository: akshara-a/Night-Ghost Architecture at a Glance ┌────────────┐ ┌───────────┐ ┌──────────────┐ ┌─────────────┐ │ Task note │──▶│ Planner │──▶│ Executor │──▶│ Reporter │ │ + config │ │ (Open LLM)│ │ (LLM + tools)│ │ (log→MD) │ └────────────┘ └───────────┘ └──────┬───────┘ └─────────────┘ │ ┌─────────────────────┼─────────────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌────────────┐ ┌────────────┐ │ Guardrail│ │ Test Runner│ │ Git Manager│ │ (paths, │ │ (sandboxed │ │ (branch, │ │ budgets)│ │ subproc) │ │ commits) │ └──────────┘ └────────────┘ └────────────┘ │ ┌─────▼──────┐ │ Local LLM │ │ (Ollama) │ └────────────┘ Key Engineering Components: - Guardrail Engine (guardrail.py): All writes are path-checked in deterministic code (resolving symlinks and ..). Denylist precedence protects .env*, migrations/**, *.pem, *.key, and lockfiles. Detects secrets and blocks command injection vectors (;, &&, |, backticks, $(), newlines). - Assertion Tampering Protection: Hard rule preventing models from "fixing" tests by weakening them. If an existing test assertion is altered or deleted, the write is instantly rejected with EXISTING_ASSERTION_MODIFIED. - Git Isolation (gitmanager.py): Never touches main or leaves your working tree dirty. Snapshots uncommitted work with git stash create, works on nightghost/YYYY-MM-DD, makes atomic ghost: <step> commits, and supports one-command rollback with nightghost discard. - Test Runner (testrunner.py): Runs pytest in a sandboxed subprocess with proxy poisoning (http_proxy=http://127.0.0.1:0, PIP_NO_INDEX=1) to enforce zero network egress. - Test Suite: 33 automated tests (pytest) covering every denial path, symlink escape, budget constraint, and pipeline execution. --- How I Built It 100% Local Inference via Ollama - Zero Cloud Dependence: Night Ghost is built strictly for 100% local, offline execution using Ollama. It runs completely disconnected from the internet, communicating over localhost:11434. - Open-Weight Coder Models: Fully tested and optimized with open models including: - Gemma 4 (gemma4:e2b / gemma4:e4b): Ultra-efficient reasoning on modest consumer hardware. - Qwen 2.5 Coder (qwen2.5-coder:14b / 7b): Deep context understanding and accurate test generation. - Llama 3 / DeepSeek-Coder-V2: Advanced multi-file refactoring. The Agent Harness - Python 3.11+, Typer, and Rich for a terminal UI. - Pydantic v2 and PyYAML for strict schema validation in nightghost.yaml. - Jinja2 for compiling transparent morning reports from JSONL action logs. --- Why Does Open Innovation Matter? 1. 100% Local Code Privacy via Ollama: Developers cannot and should not send their proprietary codebases, uncommitted diffs, or corporate repositories to third-party closed cloud APIs while they sleep. Open innovation makes running open-weight models 100% locally via Ollama viable on everyday laptops, ensuring not a single byte of code or credentials ever leaves your machine. 2. Deterministic Security Over Model Promises: Closed-source agent frameworks often rely on "system prompt polite requests" not to touch sensitive files. Night Ghost enforces security in deterministic open-source code—every path check, symlink resolution, and assertion integrity check is auditable, testable, and mathematically verified. 3. No Per-Token Metering: An autonomous multi-turn overnight loop executing dozens of test iterations would rack up unpredictable API bills on closed models. Running open-weight models 100% locally via Ollama empowers indie developers to run autonomous agents overnight completely free. --- The Spirit of It There is a distinct, quiet magic in closing your laptop with a half-solved problem, going to sleep, and waking up with your morning coffee to find: [PASS] Tests: 2 -> 6 passing (0 failing) 1. Added unit tests for charge() negative amounts: commit a1f4d92 The dreaded edge cases you didn't have the energy to write at midnight are written, tested green, and neatly committed on an isolated branch. You didn't lose your morning momentum—you woke up further ahead. That is the spirit of a benevolent Ghost in the Machine. --- Prize Categories - Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine - Best Use of Open-Weight Models (Ollama / Gemma / Llama / Qwen) - Developer Productivity & Autonomous Developer Tooling

ARGUS PRISM: The Hundred-Eyed Fact-Checker That Audits AI, Refutes Hallucinations, and Gets Paid for It This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle ARGUS PRISM checks technical claims in a draft or an AI-generated answer against current, authoritative sources. It scores each claim with deterministic math, corrects what is wrong, and produces a verification report that a freelancer can sell as a service. | Resource | Link | | :--- | :--- | | Live demo | argus-prism-studio.onrender.com | | Code | akshara-a/ARGUS-PRISM | | Partner categories | Render, Gemma, Backboard, ElevenLabs, Sentry Agent Tracing, SerpApi | --- The Problem in One Example A team is finalising a migration RFC. The draft says: > "Next.js 15 continues to support React 18 in production, and LegacyAPI v1 is recommended for high-load clusters." They ask an AI assistant to confirm it, and it answers: > "Yes, absolutely! LegacyAPI v1 is a battle-tested, rock-solid solution. You can safely deploy this to production." The answer is wrong. The assistant relied on older blog posts that still rank well. The official 2026 changelog says LegacyAPI v1 was removed, so the deployment would fail at runtime. This example comes from the project's agent walkthrough (docs/AGENT_WALKTHROUGH.md). The library names are fictional test fixtures. The assistant was not malicious. It sounded confident without checking how current or authoritative its sources were. ARGUS PRISM adds that check. --- Summary ARGUS PRISM is a fact-verification engine for technical writing and AI answers. It decides with deterministic math (source tiers, time decay, contradiction detection, and Bayesian scoring), and when sources disagree it searches for the primary source to settle the dispute. For open-source AI it uses Gemma 2 locally through Ollama, Llama 3 and Mistral 7B through Backboard, and a TabPFN-style uncertainty model, so no closed API is required. It follows a zero-persistence design: drafts are never written to disk, a database, or logs. Ghostwriters, docs agencies, DevRel teams, and migration reviewers can use it commercially, and agents can call its 15 MCP tools to verify before they answer. You can try the live Studio or run uv run python backend/demo.py locally with no API keys. All 7 benchmarks and 82 unit tests pass. --- How It Handles the Example flowchart LR S["Claim:<br/>LegacyAPI v1 is recommended<br/>for high-load clusters"] --> A["ARGUS PRISM"] A --> P1["2022 blog (Tier 3, x0.5)<br/>decayed by e^(-λt)"] A --> P2["2026 official changelog (Tier 1, x1.5)<br/>current"] P1 & P2 --> X{"Contradiction"} X --> T["Tie-breaker search<br/>against primary sources"] T --> R["REFUTED"] R --> F["Corrected sentence<br/>with citation and diff"] R --> D["Dependent claims<br/>downgraded"] The output includes: - a score with ±σ% uncertainty bounds - a claim-by-claim ledger with citations - a red and green diff of the corrections - a client-ready certificate - a 60-second spoken briefing Everything is produced in memory and none of it is stored. --- How the Pieces Fit Together ARGUS PRISM is a single pipeline. Each open-source or partner component has one job. flowchart LR IN["Draft or live URL"] --> EX["Extract claims<br/>Gemma 2 local / regex"] EX --> SR["Gather evidence<br/>SerpApi: Web, Scholar, News<br/>or DuckDuckGo"] SR --> MATH["Deterministic scoring<br/>tiers x decay x Bayes"] EX --> BB["Cross-check<br/>Backboard: Llama 3, Mistral, Gemma 2"] BB --> MATH MATH --> OUT["Verdict, diff, certificate"] OUT --> EL["Spoken debrief<br/>ElevenLabs"] MATH -. spans and latency .-> SEN["Sentry agent tracing"] OUT --> RND["Hosted on Render<br/>API, Web Studio, Dashboard"] Gemma 2, run through Ollama, extracts claims locally so private drafts stay on the machine. SerpApi (or DuckDuckGo) returns Google Web, Scholar, and News results for the evidence pool. Backboard reaches Llama 3, Mistral, and Gemma 2 with one key to produce an agreement ratio. The deterministic kernel then applies source tiers, freshness decay, contradiction detection, and a Bayesian update. ElevenLabs turns the result into a 60-second spoken debrief in one of three voices. Sentry records a span for each pipeline stage with latency and cost visibility, and Render hosts the API, the Web Studio, and the dashboard from one blueprint. --- 1. What I Built 1.1 The problem LLMs write fluent text that is often wrong. They state outdated facts, such as an API removed last quarter, with total confidence. Single-pass RAG makes this worse. It retrieves the top-ranked pages, and those are often SEO-heavy 2022 tutorials that contradict the current changelog. This hurts people who get paid for correctness. Technical ghostwriters and freelance writers risk their credibility, and sometimes the contract, over a single wrong version number. DevRel and docs agencies ship tutorials that must not break on copy-paste. Due-diligence reviewers and consultants sign off on migration RFCs. AI agent builders need a trustworthy verify-before-you-answer tool. 1.2 The solution ARGUS PRISM treats search engines as telemetry streams. It does not ask an LLM whether a claim "seems right." It computes a verdict with explicit, reproducible math. Official registries and docs count 1.5x, community hubs 1.0x, and SEO blogs 0.5x. Evidence ages as e^(-λt), with λ inferred from how fast the domain moves. Opposing claims on the same entity are flagged as contradictions, and a high-severity conflict triggers a tie-breaker search against primary sources. An evidence graph downgrades any claim that depends on a refuted one. A Bayesian uncertainty model (TabPFN-style) gives every score calibrated ±σ% bounds. The auto-fixer rewrites refuted claims with primary citations and shows the change as a git-style diff. 1.3 The Side-Hustle Business Model ARGUS PRISM is built so one person can run a paid verification service. A freelancer runs a client's draft through the engine, reviews the result, and delivers a branded Verification Certificate, a corrected draft, and optional extras. The tool does the slow research. The freelancer supplies judgment and the client relationship. The service in one line > "I fact-check your technical content against current primary sources, fix what is wrong, and hand you a certificate you can show your readers or your client." !Image description The workflow flowchart LR Client["Client sends draft<br/>or a live docs URL"] --> Run["Freelancer runs<br/>argus validate --file draft.txt<br/>--client 'Client Name'"] Run --> Score["Integrity score ±σ%<br/>claim ledger + citations"] Score --> Review["Freelancer reviews<br/>contested claims"] Review --> Fix["Auto-fix: refuted claims<br/>replaced with primary sources"] Fix --> Pack["Package deliverables"] Pack --> Invoice["Invoice:<br/>Fact-Check and Verification Audit"] Invoice --> Repeat["Retainer or per-article repeat work"] What the client receives The Client Verification Certificate is a branded, print-ready HTML report with the integrity score, the claim ledger, and the time-saved figure. It is proof the content was audited and a visible line item on the invoice. The corrected draft replaces refuted claims with grounded text and primary citations, shown as a red and green diff, so the client can apply the fixes without redoing the research. The evidence dossier adds a summary for each contradiction, the full claim ledger, and the formulas used, which gives editors and compliance teams an audit trail. The verification badge is an embeddable SVG for READMEs, Notion pages, and newsletters. The academic export produces Markdown with numbered footnotes and an IEEE or APA bibliography for Substack, Medium, Ghost, or Obsidian. The spoken debrief is a 60-second audio summary in one of three voices for busy executives and sponsors. The economics The CLI estimates the manual work it replaces, so the value shows up on every report. The heuristic in the code is: estimated_hours = max(0.5, claims × 0.35 + (words ÷ 1000) × 0.5) billable_value = estimated_hours × hourly_rate (default $50/hr) For example: A short blog post with 6 claims and 600 words comes out at about 2.4 hours, or $120 at $50 an hour. A technical tutorial with 12 claims and 1,500 words comes out at 4.9 hours, or $245. A long guide or RFC with 25 claims and 3,000 words comes out at 10.2 hours, or $510. These figures come from the report's built-in heuristic, which assumes roughly 20 to 25 minutes of research per factual claim. They are estimates to anchor a conversation, not measured results or market rates. The hourly rate is configurable. Why the margins work: the open-source stack keeps the cost of goods close to zero. Local Gemma 2 and DuckDuckGo search are free, the Cost-Guard cache avoids paying twice for the same query, and the offline engine needs no keys. The one metered input is optional live SerpApi search, which the cache is designed to minimise. Pricing ladder This is an illustrative starting structure, to be validated with real clients. A per-article audit (certificate and corrected draft) suits a single post, tutorial, or docs page. A monthly retainer (a fixed number of audits, dossiers, and badges) suits agencies, newsletters, and DevRel teams with regular output. A migration RFC review (dossier, head-to-head stack comparison, and audio debrief) suits engineering managers signing off on an upgrade. The self-hosted MCP and API option gives teams the open-source engine to build "verify before you answer" into their own agents. Who buys, and what they are really buying Freelance writers and ghostwriters pay for a documented fact-check on every delivery, because one outdated version number damages credibility. DevRel and docs agencies pay for verification before publication, since tutorials that fail on copy-paste cost trust. Engineering managers and consultants pay for a second opinion backed by current changelogs, because a migration RFC built on stale advice can cause outages. AI agent builders pay for a tool their agent can call before it responds, since agents otherwise answer confidently from stale sources. Why this beats the alternatives Manual fact-checking is slow, inconsistent, and hard to document. ARGUS PRISM takes minutes per draft and gives a reproducible score with citations. Asking another LLM to double-check relies on the same stale training data and the same confident tone, whereas ARGUS PRISM uses evidence tiering, time decay, and a tie-breaker against primary sources. Plagiarism and grammar tools check wording, not whether the claims are true. Trust and privacy as selling points Clients often share unpublished drafts under NDA. Because the engine can run fully locally with zero persistence, the freelancer can promise that the draft is never stored or sent to a third-party model. That is a concrete reason to choose this service over a hosted one. !Image description 1.4 Feature map ARGUS PRISM is organised into five layers. Each layer feeds the next. flowchart LR A["Verification Core<br/>Decides what is true"] --> B["Open-Weight AI<br/>Extracts and cross-checks"] B --> C["Deliverables<br/>What clients receive"] C --> D["Interfaces<br/>How people and agents connect"] D --> E["Operations<br/>Keeps it fast, safe, and observable"] Verification Core. A six-state machine enforces one deterministic path from planning to report. Credibility tiering weights sources, freshness decay ages evidence, and a contradiction detector flags opposing claims. A tie-breaker loop resolves conflicts against primary sources, an evidence graph downgrades dependent claims, and a Bayesian posterior updates confidence from corroboration. Open-Weight AI. Gemma 2 through Ollama handles local, private claim extraction. Backboard provides a tri-model check across Llama 3 8B, Mistral 7B, and Gemma 2 9B. A TabPFN-style oracle returns class probabilities and ±σ% bounds, and a regex fallback works with no model at all. Deliverables. Clients receive a certificate, an evidence dossier, an embeddable badge, an academic export with IEEE or APA references, a 60-second spoken debrief, and a git-style auto-fix diff. Interfaces. The engine is available as an MCP server (15 tools, 4 resources, 3 prompts), a REST API with 12 endpoints, a Next.js 16 Web Studio, a Streamlit dashboard, and a CLI. Operations. The Cost-Guard cache combines an in-memory LRU with SQLite, Sentry provides tracing, and the zero-persistence design stores no draft. Security hardening covers SSRF, XSS, and CSP, and delivery uses Docker, Render, and GitHub Actions. --- 2. Demo 2.1 Links - Live app (Web Studio): argus-prism-studio.onrender.com - API health check: argus-prism-api.onrender.com - Telemetry dashboard (Streamlit): argus-prism-dashboard.onrender.com - Source code: akshara-a/ARGUS-PRISM Try the Studio in under a minute: 1. Open the Studio. 2. Click one of the six enterprise presets: FastAPI Concurrency, Kafka KRaft Consensus, PyTorch 2.5 Inductor, OAuth 2.1 Security, LegacyAPI v1 Stale Spec, or the QuantumReactJS Trap. 3. Pick a provider (DuckDuckGo, SerpApi, or the offline Mock Engine), a search engine (Web, Scholar, or News), and an extractor (regex, Gemma 2, or tri-model). 4. Press Run Deterministic Factual Audit. > The free-tier host sleeps when idle, so the first request can take a short while to wake. The Studio also has a Mock Engine for deterministic offline runs, and the presets are meant to show the range from verified to hallucinated. 2.2 Five-second quickstart No API keys needed. The offline path uses the mock provider and the regex extractor. git clone https://github.com/akshara-a/ARGUS-PRISM cd "ARGUS-PRISM" uv venv && uv pip install -e . uv run python backend/demo.py # hallucination trap, contradiction catch, # cost-guard economics, comparison, HTML dossier uv run python backend/evaluate.py # 7/7 benchmark checks 2.3 Demo storyline sequenceDiagram autonumber actor W as Freelance writer participant UI as Web Studio (Next.js) participant API as FastAPI participant ENG as ARGUS Engine participant WEB as Search provider participant AI as Open models W->>UI: Paste draft or a live docs URL UI->>API: POST /api/validate API->>ENG: run 6-state pipeline ENG->>WEB: optimistic, skeptical, temporal queries WEB-->>ENG: raw documents (cached by Cost-Guard) ENG->>AI: extract claims, triangulate models, uncertainty ENG->>ENG: tier, decay, detect conflict, tie-break ENG-->>API: score ±σ%, claim ledger, DAG API-->>UI: report + audio (base64, in-RAM) UI-->>W: gauge, claim cards, red/green diff W->>UI: Apply Fixes, then Download Certificate 2.4 What you will see The hallucination trap feeds in a made-up library (QuantumReactJS), which scores 0.0% with an empty claim ledger. The contradiction catch shows a stale 2022 tutorial saying LegacyAPI v1 is fine while a 2026 changelog says it was removed. ARGUS decays the tutorial, runs a tie-breaker query, elevates the changelog, and marks the old claim REFUTED. The auto-fix diff shows the false claim in red and the grounded replacement in green, and one click applies it to the editor. The certificate modal previews the HTML report in a sandboxed iframe, ready to download. The voice persona switch lets Rachel, Adam, or Drew read the 60-second debrief. --- 3. Code 3.1 Repository {% embed akshara-a/ARGUS-PRISM %} Link: akshara-a/ARGUS-PRISM The code is organised by responsibility. backend/src/argus/engine/ holds the state machine, scoring, contradiction detector, graph engine, auto-fixer, and exporters. llm/ contains the Gemma and Backboard clients, providers/ holds the search interface, the DuckDuckGo, SerpApi, and mock providers, and the cache, and mcp/ is the MCP server. api/ is the FastAPI server, and audio/ and observability/ hold the ElevenLabs client and the Sentry tracer. The frontend/ folder is the Next.js 16 Web Studio, and tests/ holds the 82 pytest tests. docs/ and learnings.md contain the API reference, the connector SDK guide, deployment notes, and the full architecture write-up. The Dockerfile, render.yaml, and .github/workflows/ci.yml cover the container, the Render blueprint, and CI. 3.2 Quality gates The benchmark harness (backend/evaluate.py) passes 7 of 7 checks in about 0.21 seconds, and all 82 pytest unit tests pass. CI runs on GitHub Actions, and the full suite runs offline with no API keys. --- 4. How I Built It The build is described in seven parts: architecture, scoring math, reasoning, the open-weight AI layer, platform services, interfaces, and hardening and delivery. --- Part A: Architecture 4.1 System architecture flowchart TB subgraph Clients["Clients"] WEB["Next.js 16 Web Studio"] ST["Streamlit Explorer"] CLI["CLI"] AGENT["AI Agents<br/>Claude Desktop, Cursor, any MCP client"] end subgraph Surface["Interface layer"] REST["FastAPI REST"] MCP["MCP 2.x Server<br/>15 tools, 4 resources, 3 prompts"] end subgraph Core["ARGUS Deterministic Kernel"] SM["GoF State Machine<br/>(6 master states)"] EXT["Claim Extractor"] SC["Scoring: tiers x decay x Bayes"] CON["Contradiction Detector"] GR["Evidence DAG Engine"] FIX["Auto-Fixer"] EXP["Exporters<br/>dossier, certificate, badge, academic"] end subgraph Providers["Pluggable connectors (open interfaces)"] DDG["DuckDuckGo (free, no key)"] SERP["SerpApi: Web, Scholar, News"] MOCK["Mock (offline, CI)"] CACHE[("Cost-Guard cache<br/>LRU RAM + SQLite")] end subgraph AI["Open-weight AI connectors"] GEM["Gemma 2 local (Ollama)"] BB["Backboard: Llama 3, Mistral, Gemma 2"] TAB["TabPFN-style<br/>Bayesian oracle"] RX["Regex fallback"] end subgraph Side["Side channels"] EL["ElevenLabs TTS<br/>(ephemeral base64)"] SEN["Sentry tracing"] end WEB & ST & CLI --> REST AGENT --> MCP REST & MCP --> SM SM --> EXT --> SC --> CON --> GR --> FIX GR --> EXP SM <--> CACHE CACHE <--> DDG & SERP & MOCK EXT -.-> GEM & RX SC -.-> TAB CON -.-> BB REST -.-> EL SM -.-> SEN 4.2 The six master states (GoF State pattern) Every run walks the same deterministic path. Transitions are explicit, and there is exactly one tie-breaker recursion. This is why identical inputs produce bit-identical scores. stateDiagram-v2 [*] --> STATE_INITIALIZED STATE_INITIALIZED --> STATE_PLANNING: configure(topic, domain, lambda) state STATE_PLANNING { [*] --> OptimisticVector OptimisticVector --> SkepticVector SkepticVector --> TemporalVector TemporalVector --> [*] } STATE_PLANNING --> STATE_GATHERING: vectors_ready state STATE_GATHERING { [*] --> ProviderDispatch ProviderDispatch --> Normalize Normalize --> Dedupe Dedupe --> [*] } STATE_GATHERING --> STATE_EVALUATING: documents_normalized state STATE_EVALUATING { [*] --> ExtractClaims ExtractClaims --> CredibilityTiering CredibilityTiering --> FreshnessDecay FreshnessDecay --> DetectContradictions DetectContradictions --> [*] } STATE_EVALUATING --> STATE_CONFLICT_RESOLUTION: high_severity_conflict [depth < 1] STATE_EVALUATING --> STATE_REPORTING: no_conflicts state STATE_CONFLICT_RESOLUTION { [*] --> TieBreakerQuery TieBreakerQuery --> TargetedSearch TargetedSearch --> ReEvaluate ReEvaluate --> ReconcileOrFlag ReconcileOrFlag --> [*] } STATE_CONFLICT_RESOLUTION --> STATE_REPORTING: depth == 1 state STATE_REPORTING { [*] --> BuildDAG BuildDAG --> Synthesize Synthesize --> GlobalConfidence GlobalConfidence --> EvidenceReport EvidenceReport --> [*] } STATE_REPORTING --> STATE_COMPLETED: payload_validated STATE_COMPLETED --> [*] STATE_INITIALIZED receives the topic, domain, and decay constant. STATE_PLANNING builds the optimistic, skeptical, and temporal query vectors. STATE_GATHERING dispatches to the provider, normalises documents, and deduplicates them. STATE_EVALUATING extracts claims, tiers sources, applies decay, and detects contradictions. STATE_CONFLICT_RESOLUTION runs one bounded tie-breaker round against primary sources. STATE_REPORTING builds the graph, synthesises the result, computes global confidence, and emits the report. 4.3 Claim lifecycle stateDiagram-v2 [*] --> WEAK: extracted, uncorroborated or stale (score < 50) WEAK --> VERIFIED: multi-domain corroboration, score >= 70, no conflict WEAK --> CONTESTED: opposing polarity found VERIFIED --> CONTESTED: fresher conflicting source CONTESTED --> VERIFIED: tie-breaker confirms CONTESTED --> REFUTED: Tier 1 doc overrules REFUTED --> [*] VERIFIED --> [*] A claim is VERIFIED when its score is at least 70, it has multi-domain corroboration, and no conflict is active. It is CONTESTED when sources oppose each other and the conflict is under tie-breaker evaluation or flagged as unresolved. It is WEAK when its score is below 50 because it is stale, uncorroborated, or from an unverified origin. It is REFUTED when fresher Tier 1 documentation overrules it. --- Part B: The scoring math 4.4 Credibility tier weight W(d) Tier 1 (1.5x, authoritative) covers primary sources such as github.com, gitlab.com, docs.* sites, learn.microsoft.com, python.org, pypi.org, npmjs.com, kubernetes.io, ietf.org, w3.org, and .gov and .edu domains. Tier 2 (1.0x, community) covers stackoverflow.com, stackexchange.com, lwn.net, dev.to, news.ycombinator.com, arxiv.org, infoq.com, and engineering blogs. Tier 3 (0.5x, unverified) covers Medium, SEO listicles, and the rest of the general web. 4.5 Freshness decay DecayMultiplier(t) = e^(−λ · t) t = document age in months | Domain velocity | λ | Approx. half-life | Typical examples | | :--- | :---: | :---: | :--- | | Fast: AI and web frameworks | 0.35 | about 2 months | LLM tooling, JS frameworks | | Cloud and orchestration | 0.22 | about 3 months | Docker, Kubernetes, cloud APIs | | Core systems and protocols | 0.05 | about 14 months | POSIX, Linux syscalls, RFCs | xychart-beta title "Evidence weight vs. document age (decay multiplier)" x-axis "Age in months" [0, 3, 6, 12, 18, 24] y-axis "Multiplier" 0 --> 1 line [1.0, 0.35, 0.12, 0.015, 0.002, 0.0002] line [1.0, 0.52, 0.27, 0.07, 0.02, 0.005] line [1.0, 0.86, 0.74, 0.55, 0.41, 0.30] Lines, top to bottom at 3 months: systems λ=0.05, cloud λ=0.22, fast λ=0.35. These values are computed from the formula, not measured. 4.6 Conflict discount and Bayesian update Proportional conflict discount (instead of zeroing a claim on the first dispute): DiscountedScore = RawScore × max(0.40, 1.0 − 0.15 × n_conflicts) Bayesian update: P(H|E) = P(E|H) · P(H) / P(E) 4.7 Score pipeline per claim flowchart LR D["Retrieved document"] --> T["Tier weight W(d)<br/>1.5 / 1.0 / 0.5"] D --> A["Age t (months)"] A --> E["Decay e^(−λt)"] T --> M(("×")) E --> M M --> C["Corroboration<br/>(independent domains)"] C --> B["Bayesian posterior<br/>P(H|E)"] B --> X["Conflict discount<br/>max(0.40, 1 − 0.15n)"] X --> TP["Bayesian oracle: P(VER), P(CON), P(REF)<br/>and ±σ%"] TP --> S["Claim score 0–100<br/>+ state"] --- Part C: Reasoning and self-correction 4.8 Self-correcting tie-breaker loop This is the core anti-hallucination idea. When sources disagree, ARGUS does not average them. It goes and finds a primary-source answer. flowchart TD S["Claim extracted"] --> V1["Optimistic query<br/>(general web)"] S --> V2["Skeptic query<br/>(issues, PRs, deprecations)"] S --> V3["Temporal query<br/>(release notes, changelog)"] V1 & V2 & V3 --> POOL["Document pool"] POOL --> SCORE["Tier x decay scoring"] SCORE --> Q{"High-severity<br/>contradiction?"} Q -- No --> REP["Report"] Q -- Yes --> DEPTH{"depth &lt; 1 ?"} DEPTH -- No --> FLAG["Flag as CONTESTED / unresolved"] DEPTH -- Yes --> TB["Generate tie-breaker query<br/>aimed at Tier 1 primary docs"] TB --> RS["Targeted search"] RS --> RE["Re-evaluate claims"] RE --> WIN{"Fresher Tier 1<br/>overrules?"} WIN -- Yes --> REF["Loser → REFUTED<br/>winner elevated"] WIN -- No --> FLAG REF --> REP FLAG --> REP 4.9 Evidence DAG and transitive invalidation flowchart LR A["Claim A (2026 changelog):<br/>'LegacyAPI v1 removed Mar 2026'<br/>VERIFIED"] B["Claim B (2022 blog):<br/>'LegacyAPI v1 is production-ready'<br/>REFUTED"] C["Claim C:<br/>'High-load clusters should use v1'<br/>depends on B"] D["Claim D:<br/>'Migrate to UnifiedAPI v2'<br/>ENTAILS from A"] A -- CONTRADICTS --> B C -- REQUIRES --> B A -- TRANSITIVELY_CONTRADICTS --> C A -- ENTAILS --> D classDef good fill:#d1fae5,stroke:#047857,color:#064e3b classDef bad fill:#fee2e2,stroke:#b91c1c,color:#7f1d1d classDef warn fill:#fef3c7,stroke:#b45309,color:#78350f class A,D good class B bad class C warn The graph uses four edge types. CONTRADICTS links direct opposing claims about the same entity. REQUIRES marks a prerequisite dependency. ENTAILS marks a logical consequence. TRANSITIVELY_CONTRADICTS applies when claim A refutes claim B and claim C depends on B, so C is downgraded with a transitive-risk rationale. Graph-level metrics: - Contradiction density = conflicting pairs ÷ total claim pairs (0.0 to 1.0). - Consensus centrality = corroboration weighted by node degree (0 to 100). --- Part D: The open-weight AI layer 4.10 Model layer flowchart TB IN["Draft text"] --> CHOOSE{"LLM mode"} CHOOSE -->|"--llm gemma"| G["Gemma 2 2B<br/>local via Ollama<br/>0 cost, 0 data leaves machine"] CHOOSE -->|"Backboard key set"| B["Backboard gateway<br/>one key, three open models"] CHOOSE -->|"default / offline"| R["Regex extractor<br/>deterministic, 0.2s"] B --> L["Llama 3 8B"] B --> M["Mistral 7B"] B --> GG["Gemma 2 9B"] L & M & GG --> AGR{"Agreement ratio"} AGR -->|"3 of 3"| OK["3/3 Models Concur"] AGR -->|"2 of 3"| MID["2/3 Concur: review"] AGR -->|"dissent"| HI["High Hallucination Risk"] G --> CL["Structured JSON claims"] R --> CL OK & MID & HI --> CL CL --> ENGINE["Deterministic scoring kernel"] There are three extraction paths. Gemma 2 2B through Ollama runs with --llm gemma. It is free, local, and private, but it is a small model and can miss subtle claims. The Backboard tri-model check runs when BACKBOARD_API_KEY is set. It gives a real cross-model agreement signal from Llama 3, Mistral, and Gemma 2, but needs a key and network access. Without a key it falls back to a deterministic offline simulation so demos and tests still run. The regex extractor is the default and works offline. It is instant and fully deterministic but coarse. Design principle: open models extract and cross-examine. They never decide the score. The math does. If every model is unavailable, the regex path still works end to end, which keeps CI and the benchmark deterministic. 4.11 Bayesian uncertainty oracle (TabPFN-style) Each claim becomes a 4-feature vector [W(d), age, corroboration_count, conflict_count] plus its deterministic base score. The oracle turns that into [P(VERIFIED), P(CONTESTED), P(REFUTED)] and an uncertainty interval, shown on the gauge as, for example, 94.5% (±2.4%). How it works: it is a hand-written, closed-form calibrated model. It computes a logit for each class from the features, applies a softmax, and derives ±σ from the entropy of the resulting distribution (bounded between 1.2% and 8.5%). It runs entirely in memory with no download and no GPU. What it is not: it does not load the pretrained TabPFN network. It is named for the idea, which is a prior-fitted, tabular, in-memory probabilistic classifier. Swapping in the real TabPFN behind the same evaluate_claim interface is a natural next step. --- Part E: Platform services 4.12 Zero-persistence data flow flowchart LR U["User draft"] -->|HTTPS| API["FastAPI process RAM"] API --> ENG["Engine: transient objects"] ENG --> OUT["Report + base64 audio"] OUT -->|HTTPS| U ENG -. "X no disk write" .-> DISK[("Disk / DB")] ENG -. "X no draft logging" .-> LOG[("Logs")] CACHE[("Cost-Guard cache<br/>search results ONLY")] <--> ENG note1["Cache stores search-query to results,<br/>never user drafts or claims text"] -.-> CACHE Guarantees: - Drafts and extracted claims live only in process memory for the life of the request. - No draft is written to disk, SQLite, or logs. - Audio is streamed as base64 in the HTTP response, with no server-side files. - The SQLite tier of the cache holds public search results keyed by query. It never holds user drafts. 4.13 Cost-Guard two-tier cache flowchart LR Q["Search query"] --> T1{"Tier 1: in-memory LRU"} T1 -- hit --> R["Return, sub-millisecond"] T1 -- miss --> T2{"Tier 2: SQLite<br/>.cache/serpapi_cache.sqlite"} T2 -- hit --> P["Promote to LRU, return"] T2 -- miss --> API["Live provider call"] API --> W["Write both tiers"] --> R R --> TEL["Telemetry: hit rate, calls,<br/>USD saved ($0.01/query est.), avg latency"] Benchmark result: 12 repeated requests gave 7 hits, a 58.3% hit rate, and an estimated $0.07 saved. The score stayed identical. 4.14 Deliverables pipeline flowchart LR REP["Evidence report"] --> DOS["Evidence Dossier<br/>contradiction summaries, claim ledger, formulas"] REP --> CERT["Client Certificate<br/>(HTML, billable time saved)"] REP --> BADGE["SVG badge<br/>GET /api/badge"] REP --> ACAD["Academic export<br/>[^1] footnotes + IEEE/APA"] REP --> FIXD["Auto-fixed Markdown<br/>+ git-style diff"] REP --> AUD["60s audio debrief<br/>Rachel / Adam / Drew"] BADGE --> SNIP["Markdown / HTML snippet<br/>GitHub, Notion, Substack"] ACAD --> PUB["Notion, Substack, Medium,<br/>Ghost, Obsidian"] --- Part F: Interfaces and integrations 4.15 MCP integration (15 tools) flowchart LR AG["Agent (Claude Desktop / Cursor / Inspector)"] -->|stdio or SSE| MCPS["ARGUS MCP Server"] subgraph Tools["15 Tools"] T1["validate_response"] T2["execute_research"] T3["execute_targeted_search"] T4["inspect_evidence"] T5["inspect_confidence"] T6["inspect_conflicts"] T7["compare_technologies"] T8["inspect_telemetry"] T9["generate_dossier"] T10["auto_repair_draft"] T11["crawl_and_audit_url"] T12["export_academic_markdown"] T13["generate_verification_badge"] T14["backboard_compare_models"] T15["tabpfn_bayesian_uncertainty"] end subgraph Res["4 Resources"] R1["argus://reports/latest"] R2["argus://conflicts/active"] R3["argus://reports/dossier"] R4["argus://graph/dot"] end subgraph Pr["3 Prompts"] P1["validate_response"] P2["adversarial_fact_check"] P3["migration_risk_audit"] end MCPS --> Tools & Res & Pr Agent before and after: sequenceDiagram actor Dev participant LLM as Naive LLM participant AG as ARGUS-equipped agent participant AR as ARGUS MCP Dev->>LLM: "Next.js 15 supports React 18 and LegacyAPI v1 is production-ready?" LLM-->>Dev: "Yes, absolutely!" (stale blog bias, WRONG) Dev->>AG: same question AG->>AR: auto_repair_draft(draft, domain) AR->>AR: tier, decay, tie-break to the changelog AR-->>AG: refuted claims + diff + ±σ confidence AG-->>Dev: "Not accurate. v1 was removed (source, date). Corrected text attached." 4.16 REST API (12 endpoints) | Method | Path | Purpose | | :---: | :--- | :--- | | GET | /api/health | Liveness and readiness probe | | POST | /api/fetch-url | SSRF-safe crawl of a live page | | POST | /api/validate | Full audit of a draft | | GET | /api/badge | Embeddable SVG verification badge | | POST | /api/compare-models | Backboard tri-model comparison | | POST | /api/bayesian-evaluate | Class probabilities and uncertainty interval | | POST | /api/export-footnotes | Footnoted Markdown with IEEE/APA references | | POST | /api/auto-fix | Grounded rewrite plus diff | | POST | /api/research | Adversarial multi-vector research | | POST | /api/compare | Head-to-head technology comparison | | POST | /api/chat | Documentation-anchored assistant | | GET | /api/telemetry | Cache and cost telemetry | 4.17 Head-to-head comparator compare FastAPI Django runs two research pipelines and scores each on four dimensions. The four dimensions are global evidence confidence (a deterministic score across all sources), authoritative verified claims (the count of Tier 1 verified claims), operational stability (the inverse of conflict and weak-claim density), and ecosystem freshness (exponentially decayed recency). quadrantChart title Illustrative comparator output (example shape, not real data) x-axis "Low freshness" --> "High freshness" y-axis "Low evidence confidence" --> "High evidence confidence" quadrant-1 "Strong and current" quadrant-2 "Well-evidenced but aging" quadrant-3 "Weak and stale" quadrant-4 "Fresh but thinly evidenced" "Tech A": [0.78, 0.82] "Tech B": [0.55, 0.88] !Image description 4.18 Pluggable connector design Every external dependency sits behind an interface, so contributors can add engines without touching the kernel: classDiagram class ISearchProvider { <<interface>> +provider_name str +search(query, ...) list~RawDocument~ } class DuckDuckGoSearchStrategy class WebSearchStrategy class MockSearchStrategy class CustomEnterpriseProvider ISearchProvider <|.. DuckDuckGoSearchStrategy ISearchProvider <|.. WebSearchStrategy ISearchProvider <|.. MockSearchStrategy ISearchProvider <|.. CustomEnterpriseProvider class CredibilityDecorator { +evaluate_source_tier(url) } class SerpApiCache { +get() +put() +telemetry() } class ClaimGraphEngine { +add_claim() +relate() +transitive_invalidate() } class ArgusStateMachine ArgusStateMachine --> ISearchProvider ArgusStateMachine --> CredibilityDecorator ArgusStateMachine --> SerpApiCache ArgusStateMachine --> ClaimGraphEngine The design uses the State pattern for the six-state pipeline, the Decorator pattern for credibility tiers, the Strategy pattern for swappable search providers, the Observer pattern for the traceability drawer, and the Adapter pattern for the SerpApi engines. --- Part G: Hardening, delivery, and proof 4.19 Security hardening flowchart TB subgraph Threats T1["SSRF via URL auditor"] T2["XSS in generated HTML"] T3["Malicious certificate preview"] T4["Wildcard CORS"] T5["SVG stored XSS"] T6["Regex backreference injection"] end subgraph Mitigations M1["is_safe_public_url: DNS pre-resolve,<br/>block loopback, 169.254.169.254, RFC1918,<br/>redirects disabled"] M2["http/https scheme allow-list,<br/>html.escape on every href and content"] M3["iframe sandbox=''"] M4["Origin whitelist + onrender.com regex"] M5["CSP default-src 'none'<br/>+ nosniff on badge"] M6["pattern.sub(lambda _: repl, text)"] end T1 --> M1 T2 --> M2 T3 --> M3 T4 --> M4 T5 --> M5 T6 --> M6 4.20 Tech stack The backend is Python 3.11 to 3.13 with Pydantic v2, FastAPI, and Uvicorn, and it exposes the Model Context Protocol (MCP 2.x) over stdio and SSE. The frontend is Next.js 16 with Turbopack, React 19, Tailwind CSS v4, TypeScript, and Bun, and the dashboard uses Streamlit, PyVis, and NetworkX. Open-weight models are Gemma 2 through Ollama and Llama 3 8B, Mistral 7B, and Gemma 2 9B through Backboard. Uncertainty comes from an in-memory Bayesian oracle modelled on the TabPFN idea (a closed-form softmax with no model download). Search uses DuckDuckGo, SerpApi (Google, Scholar, News), or an offline mock. ElevenLabs provides voice and Sentry provides observability. The cache is an in-memory LRU plus SQLite, and packaging and delivery use uv, pytest, Docker, GitHub Actions, and a Render Blueprint. !Image description 4.21 Deployment topology flowchart LR GH["GitHub repo"] --> CI["GitHub Actions<br/>pytest + benchmark"] GH --> RND["Render Blueprint (render.yaml)"] RND --> APIsvc["argus-prism-api<br/>FastAPI + MCP core<br/>health: /api/health"] RND --> FEsvc["Web Studio (Next.js)"] FEsvc -->|REST| APIsvc APIsvc --> EXT1["DuckDuckGo / SerpApi"] APIsvc --> EXT2["Backboard / ElevenLabs"] APIsvc --> EXT3["Sentry"] DK["Dockerfile"] --> GH LOC["Local: Ollama + Gemma 2"] -.optional.-> APIsvc 4.22 Benchmarks | # | Test | What it proves | Result | | :-: | :--- | :--- | :---: | | 1 | Hallucination trap | A fabricated library scores 0.0 with an empty ledger | Pass | | 2 | Contradiction catch | A 2026 changelog elevates over a decayed 2022 blog via tie-breaker | Pass | | 3 | Traceability | 100% of claims map to a URL, snippet, and tier | Pass | | 4 | Reproducibility | Bit-identical float scores across runs | Pass | | 5 | Adaptive λ and Bayes | λ is 0.35 for web and 0.05 for systems, and P(H|E) ∈ [0,1] | Pass | | 6 | Cost-Guard | Hit rate ≥ 50%, savings > 0, scores unchanged | Pass | | 7 | Multi-hop DAG | A dependent claim is penalized when its prerequisite is refuted | Pass | Suite runtime is about 0.21 s, with 82/82 unit tests passing. 4.23 Run it yourself CLI audit with client deliverables: python -m argus.cli validate --file article_draft.txt \ --client "Acme Ghostwriting" \ --export-report client_audit.html \ --markdown-report client_briefing.md \ --audio briefing.wav \ --llm gemma --provider duckduckgo Other commands: python -m argus.cli research "Pydantic v2 migration" --domain "Python Architecture" python -m argus.cli compare "FastAPI" "Django" python -m argus.cli dossier "PostgreSQL JSONB indexing" --output dossier.html python -m argus.cli telemetry python -m argus.cli mcp --transport stdio Local open model: ollama pull gemma2:2b Claude Desktop or Cursor config: { "mcpServers": { "argus-prism": { "command": "uv", "args": ["run", "--directory", "/path/to/ARGUS PRISM", "python", "-m", "argus.cli", "mcp"], "env": { "PYTHONUNBUFFERED": "1" } } } } --- 5. Why Does Open Innovation Matter? 5.1 What open made possible A hosted, closed fact-checking API would not suit this product. Open components make several things possible. Privacy you can verify. Ghostwriters handle unpublished client drafts, and some are under NDA. With Gemma 2 running locally through Ollama, nothing leaves the machine, and with open code a client can audit the zero-persistence claim instead of trusting a vendor policy. Cross-model checking needs model diversity. Backboard lets one key query Llama 3, Mistral, and Gemma 2 side by side. Agreement and dissent between independently trained open models is a real hallucination signal that a single closed model cannot provide. Determinism and reproducibility. The kernel is open math (tiers, decay, Bayes) and open models are used only for extraction. Anyone can re-run an audit and get the same score, so a Verified badge can be checked, not just trusted. Pluggable connectors. ISearchProvider lets a contributor add a search source, such as an internal wiki, without forking the kernel. This is the same open-kernel idea used by Airbyte and OpenTelemetry. Offline testing and zero-cost onboarding. The mock provider and the regex fallback let 82 tests and 7 benchmarks run in under a second with no keys, and the free DuckDuckGo path lets a new user try live verification at no cost. Open standards for agents. Because ARGUS speaks MCP, it works with Claude Desktop, Cursor, and any other MCP-compatible agent without a custom integration. 5.2 Limitations The regex fallback is fast and deterministic but coarse, and Gemma 2 2B is small enough to miss subtle claims. Freshness depends on publication dates from search results, which are sometimes missing or wrong. The tier lists are heuristics, so a Tier 1 domain can still be wrong and a Tier 3 source can be right. The benchmarks use the mock provider, and live-web results vary with the search engine. The uncertainty oracle is TabPFN-style rather than the pretrained TabPFN network, and without a Backboard API key the three-model consensus is a deterministic stand-in rather than real model output. The $0.01-per-query savings and $50 per hour figures are configurable estimates, not billing data. --- 6. Prize Categories ARGUS PRISM is entered in the partner categories below. Each entry below describes how ARGUS PRISM uses the technology. Best Use of Render. A blueprint deploys three services: the FastAPI and MCP API, the Next.js Web Studio, and the Streamlit dashboard. The API exposes /api/health. Best Use of Gemma. Gemma 2 2B runs locally through Ollama for private claim extraction (--llm gemma), and Gemma 2 9B is the third voter in the tri-model check. Best Use of Backboard. One key queries Llama 3 8B, Mistral 7B, and Gemma 2 9B and reports an agreement ratio (3/3 Concur, 2/3 Concur, or High Hallucination Risk). Best Use of ElevenLabs. A 60-second spoken debrief with three personas (Rachel, Adam, and Drew) is streamed as base64, with nothing stored on the server. Best Use of Sentry Agent Tracing. Each pipeline stage is a span with latency visibility, and the Cost-Guard and Telemetry panel includes a flamegraph view. Best Use of SerpApi. A SerpApi provider with Google Web, Google Scholar, and Google News engines supplies the evidence pool, behind a cache that tracks credits saved. ---

Exhale: The 5-Step Emotional Circuit Breaker This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass What I Built I built Exhale: The 5-Step Emotional Circuit Breaker, an acute mental health application explicitly engineered to push you away from screens and force you to literally touch grass. When a developer or student suffers an acute cognitive breakdown (e.g., "I've been stuck on this bug for 7 hours, my heart is racing, I feel like a failure"), traditional commercial apps try to keep you online with infinite feeds. Exhale reverses this completely: it acts as an emotional circuit breaker that mandates you step outside and touch grass. You submit a single sentence about your distress. Exhale analyzes the somatic emotion, anchors it with hyper-local weather/solar telemetry, and applies wisdom from worldwide cultural nature lineages. It then generates a 5-step grounding mission, aggressively locks your screen, and won't unlock until you touch grass. [ Acute Emotional Distress ] │ ▼ ┌───────────────────────┐ │ Exhale Input Console │ ◄── Raw 1-sentence brain dump └───────────┬───────────┘ │ ▼ ┌─────────────────────────────────┐ │ Live Solar & Weather Telemetry │ ◄── Open-Meteo GPS calibration │ 15 Global Nature Lineages │ ◄── Ancestral somatic grounding │ Sovereign Open-Weight Inference │ ◄── 3-Tier cascade (Hermes 3 / Groq) └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Strict 5-Stage Somatic Arc │ ◄── Touch → Sight → Sound → Smell → Temp └────────────────┬────────────────┘ │ ▼ ┌─────────────────────────────────┐ │ Full Hardware Lockout │ ◄── Tab penalties, OLED pocket mode, │ Multimodal Proof-of-Touch │ haptics, & vision verification └─────────────────────────────────┘ Who is it for? Chronically online developers, remote workers, and anyone experiencing sensory overload or a panic attack who desperately needs to close their laptop, step into the living biosphere, and touch grass. Anti-Engagement: Forcing You to Touch Grass To truly make the screen the shortest part of the experience, the app employs strict Anti-Engagement Mechanics: - Hardware Screen Lock & Tab Violations: If you switch browser tabs to avoid going outside to touch grass, the Page Visibility API triggers an alert and resets your 10-minute timer. - Pocket Mode & Haptics: The screen turns pitch black (OLED #000000) so you aren't tempted to look at it. The Web Speech API narrations and navigator.vibrate box breathing pacer guide you while the phone stays in your pocket as you walk out to touch grass. - Accelerometer & Vision Verification: The DeviceMotion API verifies you are actually walking away from your desk. Finally, an in-memory vision classifier requires a "Proof of Touch" photo of an organic object to verify you actually touched grass (or bark, leaves, stone) before unlocking the app. Proof of Touch in Action: The app actively rejects digital monitors and tracks if you try to tab away! !Image description The Clinical Neuroscience: The Strict 5-Stage Somatic Arc Why does every Exhale mission contain strictly five sequential steps? In acute distress, cognitive overload impairs executive decision-making. Asking an overwhelmed person to interpret vague advice produces decision fatigue. Exhale adheres to a scientifically validated, 5-stage sequential somatic arc that progressively re-engages the nervous system: [ Step 1: Touch ] ──► Immediate Tactile Earth Contact (Discharges static bodily heat) │ [ Step 2: Sight ] ──► Panoramic Optic Flow & Horizon Scan (Dissolves screen convergence) │ [ Step 3: Sound ] ──► Acoustic Orientation & Natural Frequencies (Induces alpha oscillations) │ [ Step 4: Smell ] ──► Olfactory Vagal Stimulation (Geosmin & phytoncides engage vagal brake) │ [ Step 5: Temp ] ──► Thermoreceptive & Postural Integration (Roots body before re-entering) 1. Step 1 — Touch (Tactile Earth Contact): Direct physical contact with living bark, unpolished stone, soil, or rain on open hands. Tactile grounding dissipates positive electrostatic surface charges and provides an immediate somatosensory reality anchor. 2. Step 2 — Sight (Panoramic Optic Flow): Gazing at the furthest visible horizon line, cloud formations, or canopy treetops for 45 seconds. Broad optic flow relaxes the ciliary eye muscles, directly deactivating the screen-induced "convergence tunnel" that sustains sympathetic fight-or-flight arousal. 3. Step 3 — Sound (Acoustic Orientation): Closing your eyes for 45 seconds to isolate ambient natural acoustics (canopy wind, distant birdsong, rain patter). Natural acoustic white noise lowers baseline acoustic stress thresholds and prompts alpha-wave (8–12 Hz) synchronization. 4. Step 4 — Smell & Respiration (Olfactory Vagal Stimulation): Deep nasal inhalation of damp soil geosmin, crushed foliage phytoncides (alpha-pinene, limonene), or crisp ambient air. Airborne phytoncides stimulate olfactory bulb pathways that trigger the parasympathetic vagal brake within seconds. 5. Step 5 — Temperature & Postural Integration: Thermoreceptive awareness of atmospheric wind or solar warmth against the skin, paired with a deliberate diaphragmatic exhale and rooted posture before stepping back inside. The Auto-Healing Step Normalizer Open-weight foundation models running in the wild can occasionally omit steps or format irregularly under varying temperatures. To prevent schema failures or truncated protocols, Exhale’s backend implements an Auto-Healing Step Normalizer (_normalize_and_enforce_five_steps): - If an LLM returns 3 or 4 steps, the engine evaluates which sensory modalities were omitted, dynamically synthesizes the missing sensory stages from our canonical cultural and weather matrices, and guarantees sequential numbering (1, 2, 3, 4, 5). - If an LLM returns more than 5 steps, it truncates cleanly to the top 5. - The Pydantic schema enforces min_length=5, max_length=5 with zero exceptions. --- The 15 Proven Global & Scientific Nature Lineages To provide the grounding protocols, Exhale bridges modern neurobiology with centuries of ancestral nature wisdom across 15 distinct world traditions. The AI uses these frameworks to generate your personalized offline mission: | Framework | Native Script & Region | Lineage & Core Philosophy | Clinical Evidence & Trials | | :--- | :--- | :--- | :--- | | Japanese Shinrin-yoku | 森林浴 (Japan) | Forest bathing; airborne phytoncides; Komorebi dappled canopy sunlight. | Chiba University: 15.8% drop in salivary cortisol; 53% surge in NK immune cell activity. | | Indian Pancha Mahabhuta | पञ्चमहाभूत (Vedic) | Earth element (Prithvi) calibration; discharging static bodily electrical potential. | Grounding dissipates positive electrical charge, resetting autonomic vagal brake. | | Tamil Ainthinai & Siddha | ஐந்திணை (Sangam) | 5 sacred eco-landscapes (Kurinji, Mullai, Marutham...) & Manvaasanai petrichor. | Inhalation of geosmin triggers immediate endorphin release and emotional grounding. | | African Ubuntu & Khoisan | Ubuntu / Ilẹ̀ (Southern Africa) | "I am because we are"; barefoot optic horizon orientation & biosphere kinship. | Panoramic optic flow stimulates brainstem nuclei, inhibiting hyperactive amygdalar fear conditioning. | | Chinese Daoist Ziran & Wu Wei | 自然 / 无为 (Daoism) | Spontaneous nature alignment; grounding agitated Yang thoughts into Yin soil. | Downregulates sympathetic arousal through rhythmic Zhan Zhuang tactile tree-contact. | | Scientific Polyvagal & ART | Porges & Kaplan (Neurobiology) | Polyvagal autonomic regulation + Attention Restoration Theory (ART). | Outdoor sensory "soft fascination" restores directed prefrontal attention depleted by code debugging. | | Indigenous Lakota Hózhó | Mitákuye Oyásʼin (Lakota/Diné) | "All My Relations"; 4-cardinal-direction alignment; touching Grandmother Earth. | Attenuates acute depersonalization through spatial-cardinal tactile orientation. | | Hawaiian Aloha ʻĀina | Aloha ʻĀina (Polynesian) | Sacred soil kinship; divine breath (Hā) synchronized with trade winds. | Synchronizes heart rate variability (HRV) with oceanic and canopy airflow patterns. | | Celtic Gaelic Dùthchas | Dùthchas & Caim (Celtic) | Hereditary belonging to ancient moss/stone; tracing protective sanctuary circle. | Perceptual boundary-setting relieves acute cognitive intrusion and rumination spirals. | | Islamic Sufi Tafakkur | تفكّر (Sufi Contemplation) | Contemplation of living cosmic signs (Ayat) in shifting desert wind and stone. | Sustained focal observation induces sustained alpha-wave brain oscillations (8–12 Hz). | | Māori Papatūānuku | Papatūānuku (Aotearoa) | Earth Mother kinship; volcanic soil contact; Tāne Mahuta fern respiration. | Soil microflora (Mycobacterium vaccae) contact stimulates serotonin synthesis. | | Korean Pungryu & Salim | 풍류 / 산림 (Silla Era) | Flowing with mountain winds through pine mist & granite ridges. | Pine pinene inhalation combined with light aerobic walking enhances cerebral perfusion. | | Greco-Roman Stoic Sympatheia | Συμπάθεια (Marcus Aurelius) | "The View from Above": cosmic contemplation of universal natural unity. | Radical cognitive decentering disrupts acute catastrophe ideation. | | Nordic Friluftsliv | Friluftsliv (Scandinavia) | Open-air elemental resilience; embracing brisk boreal winds and rain. | Mild cold thermogenesis activates brown adipose tissue, increasing norepinephrine release and mental lucidity. | | German Waldeinsamkeit | Waldeinsamkeit (Romanticism) | Restorative solitude amidst beech and spruce canopies away from urban noise. | Prolonged acoustic silence lowers baseline acoustic stress thresholds and alleviates sensory overload. | !Image description Demo Here is a look at the "anti-engagement" UI, the hardware lockouts, and a fully generated physical grounding protocol: Exhale - Click Here for Live Demo !Image description The image displays a customized 5-step "Nighttime Forest Breath" sensory protocol generated by the Exhale app, which anchors the user's grounding mission to the current nocturnal weather and atmospheric conditions: !Image description The image displays the final "Attestation" phase of the Exhale app's grounding protocol, greeting the user with the message "Welcome back to reality." upon the completion of the circuit breaker. This screen summarizes the completed session by displaying the initial somatic diagnosis (acute somatic anxiety and chest tightness) alongside a reassuring message about the user's outdoor immersion. It heavily emphasizes the app's zero-retention privacy model, confirming that the "Volatile RAM [is] Dissolved" and that "0 Bytes" of data were persisted. Additionally, the dashboard logs session metrics such as "Offline Immersion" time, "Steps Paced," and "Touch Witness" type, while offering options to log current feelings (Calmer, Grounded, Clear-Headed) and export an "Official Ephemeral Attestation" certificate as a PNG or TXT file: !Image description -- Core Features Showcased: - Pocket Mode (OLED Blackout): The screen turns pitch black to save power, using the Web Speech API to narrate the mission so you can keep the phone in your pocket. - Pocket Haptics: The navigator.vibrate API pulses a 4-4-4-4 box breathing pacer (Inhale, Hold, Exhale, Hold) directly into your leg. - Proof of Touch: An in-memory vision classifier verifies you actually touched an organic object (bark, leaves, stone) before releasing the lock, strictly rejecting digital screens. Code The entire project is open-source, features a zero-retention architecture, and is available here: Exhale - Source Code How I Built It Exhale is built on a decoupled, production-grade microservices architecture orchestrated via Render's Infrastructure-as-Code (render.yaml): - Backend AI Runtime: A Python FastAPI service running Ollama and the Hermes-3 (Open-Weight 8B) model. This is containerized via multi-stage Docker and deployed as a Render Web Service (GPU Accelerated). - Frontend SPA: A brutalist React 18 + TypeScript + Vite PWA. It leverages offline Service Worker caching so it works on the trail without a signal, and taps into native browser APIs (DeviceMotion for step pacing, Web Audio API for solfeggio drone synthesis, and Page Visibility API for tab-switch penalties). - Context Engines: Integrates Open-Meteo for local solar/weather anchoring to contextualize the AI's grounding advice to the user's immediate physical environment. --- System Architecture Exhale is built on a decoupled, production-grade microservices architecture orchestrated via Render's Infrastructure-as-Code (render.yaml): ┌────────────────────────────────────────────────────────┐ │ CLIENT LAYER (PWA) │ │ React 18 + TypeScript + Vite │ │ • Service Worker Offline Cache (Zero-Signal Trails) │ │ • Web Audio API (432Hz Solfeggio Drone Generator) │ │ • Page Visibility & DeviceMotion APIs │ └──────────────────────────┬─────────────────────────────┘ │ HTTPS / JSON (Zero Retention) ▼ ┌────────────────────────────────────────────────────────┐ │ BACKEND API (Render) │ │ FastAPI + Python 3.13 │ │ • Cooperative Cancellation Tokens (HTTP 499 on abort) │ │ • Open-Meteo High-Resolution Weather & Lux Telemetry │ │ • In-Memory Color/Texture Vision Classifier │ │ • Auto-Healing 5-Step Normalizer │ └──────────────────────────┬─────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────┐ │ 3-TIER SOVEREIGN INFERENCE CASCADE │ │ Tier 1: Sovereign Local Ollama (Nous Hermes 3 8B) │ │ Tier 2: High-Speed Open-Weight Cloud (Groq LPUs) │ │ Tier 3: Deterministic In-Memory Neuro-Cultural Engine │ └────────────────────────────────────────────────────────┘ --- Architectural Resilience: The 3-Tier Sovereign Inference Cascade A mental health circuit breaker cannot return a 502 Bad Gateway, hang on cold-start timeouts, or display an unhandled exception when someone is having a panic attack. To deliver 100% uptime, zero data retention, and sub-second response times, Exhale implements an automated 3-Tier Sovereign Cascade: flowchart TD Req["Incoming Distress Input"] --> T1 subgraph T1 ["Tier 1: Sovereign Local Ollama (Hermes 3)"] T1_Check["Check Ollama Daemon (hermes3:latest)"] T1_State["Enabled via ENABLE_OLLAMA=true"] T1_Exec["Local GPU/CPU Inference (format: json)"] end T1 -->|"Success"| R1["Return Dynamic Mission (0 Cloud Leakage)"] T1 -->|"ENABLE_OLLAMA=false / Timeout / Insufficient RAM"| T2 subgraph T2 ["Tier 2: Open-Weight Cloud LPUs (Dynamic Auto-Discovery)"] T2_Check["GET /v1/models (Real-Time Groq Catalog Discovery)"] T2_Exec["Dynamic LPU Execution (Sub-second ~400ms Latency)"] end T2 -->|"Success"| R2["Return Dynamic Mission (Tier 2 Cloud)"] T2 -->|"Network Offline / Key Missing"| T3 subgraph T3 ["Tier 3: Deterministic In-Memory Neuro-Cultural Engine"] T3_Matrix["Compiled Somatic & Weather Adaptation Matrices"] T3_Exec["Zero-Dependency Volatile RAM Synthesis (0ms)"] end T3 --> R3["Return Guaranteed Offline Grounding Protocol (100% Uptime)"] 1. Tier 1: Sovereign Local Ollama (Nous Hermes 3 8B) The primary tier executes open-weight inference locally on bare metal. The raw emotional input is processed through Nous Hermes 3 8B, a model renowned for nuanced steering, alignment, and emotional empathy. Zero bytes ever leave the host machine. 2. Tier 2: High-Speed Open-Weight Cloud (Groq LPUs) If local Ollama is disabled or unreachable, Exhale seamlessly cascades to Tier 2. Rather than hardcoding decommissioned model endpoints, the backend dynamically queries Groq's active model catalog (GET /v1/models), selects the optimal open-weight model in real time, and completes structured JSON inference in ~400ms. 3. Tier 3: Deterministic In-Memory Neuro-Cultural Engine If the network is completely severed or API keys are missing, Tier 3 takes over instantly. Built directly into backend RAM, this deterministic circuit breaker matches distress keywords and weather telemetry against compiled multi-dimensional matrices, generating a clinically grounded, 5-step protocol in 0ms with zero external dependencies. 4. Cooperative Cancellation Token Architecture If a user closes their tab, clicks "Cancel Generation", or navigates away mid-flight, Exhale avoids wasting compute. A background disconnect watcher monitors the ASGI socket via request.is_disconnected() and triggers a CancellationTokenSource. This immediately aborts the active async inference task, frees memory, and returns an HTTP 499 status cleanly. --- Why Open-Weight Models & Data Sovereignty Matter Raw emotional vulnerability is the most sensitive personal data a human being can express. Closed-source commercial AI platforms routinely ingest user prompts into training corpora, logging sensitive mental health admissions on corporate servers. Exhale proves that open-source AI is the only ethical foundation for mental health technology: - Absolute Zero Data Retention: Exhale has no database. No PostgreSQL, no MongoDB, no Redis, and no analytics trackers. User distress input exists exclusively in volatile RAM for the single inference cycle (~400ms) and is purged immediately. - Cache-Destruction HTTP Headers: Every response is sealed with strict privacy directives: Cache-Control: no-store, no-cache, must-revalidate, max-age=0 Pragma: no-cache Expires: 0 X-Data-Retention: zero X-Circuit-Breaker: engaged - Cryptographic Proof of Purge: At the conclusion of each mission, Exhale generates an HTML5 Canvas "Field Log Receipt" stamped with a cryptographic SHA-256 volatile RAM release hash, providing the user visual and mathematical verification that their input was wiped. --- The Container Memory Challenge: Engineering for Render's Free Tier Deploying heavy foundation models on cloud infrastructure introduces a classic real-world constraint: - The Reality of Container Limits: Render’s generous Free Tier provides 512 MB of total RAM. An open-weight 8B model like Nous Hermes 3 requires ~4.7 GB of disk storage and ≥ 4 GB to 6 GB of RAM to run inference locally. Attempting to run Ollama with Hermes 3 inside a 512 MB container triggers an instant Out-Of-Memory (OOM) kill. How We Engineered the Solution: To deliver a rock-solid, lightning-fast live demo for hackathon judges while preserving full support for self-hosted sovereign hardware: 1. ENABLE_OLLAMA=false by Default on Render Free Tier: - In our startup orchestrator (start.sh), the local Ollama daemon boot is cleanly bypassed when running on constrained instances. - Container RAM consumption plummets from ~500 MB down to ~35 MB (over 14× below Render's memory ceiling). - Container cold-boot time drops from 3 minutes down to 1.5 seconds. 2. Seamless Cloud LPU Delegation (Tier 2): - The backend routes the request to Groq's high-speed open-weight LPUs, returning structured 5-step protocols in ~400ms. 3. Zero-Dependency Fallback (Tier 3): - If unauthenticated or offline, Tier 3 synthesizes tailored protocols in 0ms directly from compiled RAM matrices. Activating Tier 1 Hermes 3 Locally (100% Sovereign Mode) For users running on local workstations, workstations with GPUs, or Render Starter+ instances (≥ 4 GB RAM), switching to 100% self-hosted Hermes 3 takes a single boolean flag: # 1. Clone the repository git clone https://github.com/akshara-a/Exhale.git cd Exhale # 2. Toggle the boolean flag to activate Tier 1 Local Hermes 3 export ENABLE_OLLAMA=true export OLLAMA_MODEL=hermes3:latest # 3. Launch via Docker Compose or Uvicorn docker compose up --build The container automatically boots the Ollama daemon, pulls hermes3:latest, and processes inference 100% on your own hardware with zero data ever leaving your machine. --- Prize Categories I am entering this project into the following categories: - Best Use of Render: The entire architecture is deployed using a single-click Render Blueprint (render.yaml), utilizing a Render GPU Web Service to host the heavy FastAPI/Ollama backend and a Render Static Site for the React frontend. - Best Use of Open-Weight Models: Utilizes Hermes 3 8B strictly for its ability to provide private, zero-retention somatic processing without leaking sensitive mental health data to commercial cloud providers. <!-- Thanks for participating! -->