{"id":48795738,"url":"https://github.com/syntechrev/odia","last_synced_at":"2026-05-30T06:00:32.135Z","repository":{"id":343888591,"uuid":"1179549247","full_name":"SynTechRev/ODIA","owner":"SynTechRev","description":"Civic-accountability intelligence platform for local-only forensic audit of legal \u0026 government documents. 10-detector anomaly engine, Cross-Entity Analysis Protocol V1.0, multi-jurisdictional. Python 3.11+, FastAPI, Next.js, Electron desktop. MIT-licensed.","archived":false,"fork":false,"pushed_at":"2026-05-29T01:57:51.000Z","size":16058,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-29T03:23:59.735Z","etag":null,"topics":["anomaly-detection","civic-accountability","civic-tech","electron","fastapi","forensic-audit","nextjs","ocr","open-government","public-records","python","surveillance-accountability","transparency"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SynTechRev.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":"audit_manifest.schema.json","citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T06:13:01.000Z","updated_at":"2026-05-25T12:53:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"f3526ab6-dad2-4f80-87e7-e929eaeb6f71","html_url":"https://github.com/SynTechRev/ODIA","commit_stats":null,"previous_names":["syntechrev/odia"],"tags_count":56,"template":false,"template_full_name":null,"purl":"pkg:github/SynTechRev/ODIA","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SynTechRev%2FODIA","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SynTechRev%2FODIA/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SynTechRev%2FODIA/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SynTechRev%2FODIA/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SynTechRev","download_url":"https://codeload.github.com/SynTechRev/ODIA/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SynTechRev%2FODIA/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33681809,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-30T02:00:06.278Z","response_time":92,"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":["anomaly-detection","civic-accountability","civic-tech","electron","fastapi","forensic-audit","nextjs","ocr","open-government","public-records","python","surveillance-accountability","transparency"],"created_at":"2026-04-13T23:05:55.755Z","updated_at":"2026-05-30T06:00:32.104Z","avatar_url":"https://github.com/SynTechRev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# O.D.I.A. — Oraculus Decimus Intellect Analyst\n\nA general-purpose **civic accountability intelligence platform** for forensic\nanalysis of legal and government documents.\n\nIngest legal documents (PDF, XML, JSON, TXT), detect anomalies across ten\nspecialized layers (fiscal, constitutional, surveillance, procurement, signature,\nscope, governance, administrative, grant compliance, **cross-entity**),\nreconstruct contract lineages, evaluate compliance against the ACLU CCOPS\nframework, sweep cross-entity references via the Cross-Entity Analysis Protocol\nV1.0 (May 2026), and produce audit-ready reports — all locally, with full\nSHA-256 provenance.\n\n**Repository**: https://github.com/SynTechRev/ODIA\n**License**: MIT\n**Current version**: **3.4.0** — *Jurisdiction tracking · DB-persisted upload audits · Inline RAIA synthesis*\n([release notes](https://github.com/SynTechRev/ODIA/releases/tag/v3.4.0))\n**Python**: 3.11+\n\n---\n\n## Try It Now\n\n### Desktop App (recommended for non-developers)\n\nStandalone installer — no Python, Docker, or command line required. All\nanalysis runs locally on your machine.\n\nDownload the latest installer from the\n[**Releases page**](https://github.com/SynTechRev/ODIA/releases/latest):\n\n| Platform | Installer | Architecture |\n|----------|-----------|--------------|\n| **Windows** | `ODIA-Setup-3.4.0.exe` | x64 |\n| **macOS (Apple Silicon)** | `ODIA-3.4.0-arm64.dmg` | arm64 (M1 / M2 / M3 / M4) |\n| **macOS (Intel)** | `ODIA-3.4.0-x64.dmg` | x64 |\n| **Linux** | `ODIA-3.4.0.AppImage` | x64 |\n\n**Direct download links (v3.4.0):**\n- [Windows x64](https://github.com/SynTechRev/ODIA/releases/download/v3.4.0/ODIA-Setup-3.4.0.exe)\n- [macOS Apple Silicon (arm64)](https://github.com/SynTechRev/ODIA/releases/download/v3.4.0/ODIA-3.4.0-arm64.dmg)\n- [macOS Intel (x64)](https://github.com/SynTechRev/ODIA/releases/download/v3.4.0/ODIA-3.4.0-x64.dmg)\n- [Linux AppImage](https://github.com/SynTechRev/ODIA/releases/download/v3.4.0/ODIA-3.4.0.AppImage)\n\n**System Requirements:**\n- **Windows:** Windows 10 (64-bit) or later\n- **macOS:** macOS 10.15 (Catalina) or later\n- **Linux:** Ubuntu 18.04+ or equivalent (requires `libfuse2`)\n\n**First-time setup walkthrough**:\n[docs/AUTOMATION_SETUP.md](docs/AUTOMATION_SETUP.md) covers everything from\ndownload through optional scheduled-automation setup, written for non-\ndevelopers. Start there if you're new.\n\n### With Docker (containerized; no Python/Node required)\n\n```bash\ndocker build -t odia . \u0026\u0026 docker run -p 8080:8080 odia\n```\n\nOpen `http://localhost:8080`. The full platform runs in a single container.\n\n### With Python (CLI / source workflow)\n\n```bash\ngit clone https://github.com/SynTechRev/ODIA.git \u0026\u0026 cd ODIA \u0026\u0026 pip install -e .\npython scripts/run_audit.py --source data/demo/ --output reports/demo/\n```\n\nOpen `reports/demo/audit_report.md` to see 10 synthetic documents analyzed\nacross the ten-detector pipeline. Full walkthrough: [QUICKSTART.md](QUICKSTART.md)\n\n### Mobile (PWA — v2.9.0)\n\nOpen your O.D.I.A. instance in **Safari (iOS)** or **Chrome / Edge / Samsung\nInternet (Android)** and add to home screen — installs as a fullscreen app\nwith the gold-swirl icon, offline shell, and native-feel pull-to-refresh on\nlong-list pages. No App Store, no Play Store, no review cycle.\n\n| Platform | Distribution | Install path |\n|---|---|---|\n| **iOS** | Safari | Share → Add to Home Screen |\n| **Android** | Chrome / Edge / Samsung Internet | \"Install\" prompt in-app, or three-dot menu → Install app |\n| **Desktop** | Chromium-based browsers | Install icon in URL bar |\n\nThe PWA inherits everything the desktop frontend ships: gemstone palette,\ntexture system, Manual Triggers panel, RAIA synthesis, evidence packet\nexport. Mobile-specific: card-layout file table, 44px touch targets,\npull-to-refresh on Documents/Results/Anomalies.\n\nNative iOS + Android (Capacitor / App Store / Play Store) are deferred\nto v2.9.1+ pending Apple Developer + Google Play Console accounts.\n\nFull walkthrough: [docs/MOBILE.md](docs/MOBILE.md)\n\n---\n\n## Quick Start (for developers)\n\n```bash\n# Clone and install\ngit clone https://github.com/SynTechRev/ODIA.git\ncd ODIA\npip install -e \".[dev]\"\n\n# Run tests (3000+ tests across the analysis, ingestion, orchestrator,\n#  webhook, dashboard, and Legistar suites)\npytest\n\n# Start the API server\nuvicorn oraculus_di_auditor.interface.api:app --reload\n\n# Start the frontend (separate terminal)\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n# Open http://localhost:3000\n```\n\n---\n\n## What's New in v3.x (current)\n\nThe v3 release line shipped automated multi-CMS scraping + ingestion + cross-jurisdiction RAIA synthesis at scale. Empirically validated on **5 jurisdictions / 910 documents / 601 anomalies** across **4 distinct CMS platforms** (CivicPlus, Revize, WordPress, Drupal + Questys CMX).\n\n**v3.4.0 — Jurisdiction tracking · DB-persisted audits · Inline RAIA · SynTechRev brand** ([release notes](https://github.com/SynTechRev/ODIA/releases/tag/v3.4.0))\n\nThe operator experience release. Every upload audit now persists its documents, analyses, and anomalies to the backend database so they appear in the Documents, Anomalies, and Synthesis pages alongside webhook-scraped data. Dinuba brought on as the fifth jurisdiction, contributing 62 documents and 49 critical findings — the highest critical-anomaly density corpus yet.\n\n- **Jurisdiction field on Upload page** — tag every audit batch at submission time; value persists in localStorage across page navigations so multi-batch ingestion requires no re-typing\n- **Upload audit DB persistence** — `_persist_upload_document` saves each document + analysis + anomalies to `documents`/`analyses`/`anomalies` tables on every upload audit run (previously only webhook-ingested data appeared in the UI evidence library)\n- **Backend audit history** — `GET /api/v1/audit/history` returns paginated lightweight summaries from `mesh_execution_jobs.results_json`; results page syncs from backend on mount so history survives server restarts\n- **Audit history scaled to 10,000 entries** — frontend store switched from full `AuditResults` payloads (~100–500 KB each) to lightweight metadata summaries (~300 bytes), eliminating the 5–10 MB localStorage ceiling\n- **`GET /api/v1/audit/results/{id}` DB fallback** — serves completed results from the database when the in-memory job has been evicted after a server restart\n- **Inline RAIA synthesis** — \"Run RAIA Synthesis\" button on the Synthesis page now calls `POST /api/v1/triggers/raia-synthesize-all` directly and renders the Markdown report inline with Copy + Download controls; no redirect to Automation page required\n- **RAIA jurisdiction source fixed** — synthesis now queries the `documents` table for known jurisdictions instead of reading the `config/multi_jurisdiction/` file stubs (which contained only `example_city_a/b/c`)\n- **Pipeline ingestion banner** — Results history page surfaces webhook-scraped document count with a direct link to the Documents library even when no upload audits have been run\n- **SynTechRev brand** — octopus logo replaces default icon across all six slots: browser favicon (16/32/48 px), PWA icons (192/512/maskable-512 px), Electron dock/taskbar (1024 px), Windows titlebar ICO (16–256 px)\n- **34 U.S.C. § 10152 JAG statute embedded** — `grant:jag-funded-surveillance` findings now cite the Byrne JAG authorization statute with plain-language statute text embedded via the legal resolver\n\n**v3.3.1 — PyYAML dependency + resolver CWD-independence** ([release notes](https://github.com/SynTechRev/ODIA/releases/tag/v3.3.1))\n\n- Declared `pyyaml` as an explicit dependency (was an undeclared transitive dep that broke fresh installs)\n- `LegalResolver` no longer assumes CWD is the repo root — resolves paths relative to its own module file, fixing `FileNotFoundError` on desktop and subprocess launches\n\n**v3.3.0 — USC legal corpus integration** ([release notes](https://github.com/SynTechRev/ODIA/releases/tag/v3.3.0))\n\n- Full United States Code corpus (53 titles, 52,586 sections) indexed as a git submodule via `nickvido/us-code`\n- `LegalResolver` service pre-warms the index at boot; `GET /api/v1/legal/status` surfaces corpus health\n- USC citation parser recognises `X U.S.C. § NNN` patterns and resolves to statute text for plain-language embedding\n\n**v3.2.5 — Microsoft Word + scanned TIFF ingestion** ([release notes](https://github.com/SynTechRev/ODIA/releases/tag/v3.2.5))\n\nCloses the format gap for legacy civic-records archives. Tulare County's Questys CMX archive serves ~20 years of Board of Supervisors agendas, packets, resolutions, and staff reports as a mix of PDF / DOC / DOCX / HTML / scanned TIFF. v3.2.4 recognised only PDF and HTML; v3.2.5 adds:\n\n- **`.docx`** via `python-docx` (paragraphs + tables, headers/footers skipped)\n- **`.doc`** (OLE binary, pre-2013 Word) via `antiword` / `libreoffice` subprocess with graceful empty-text fallback\n- **`.tif` / `.tiff`** multi-page OCR via `PIL.Image.seek` + `pytesseract` (scanned 2001-2009 microfilm records)\n- Magic-byte sniffing in the async-scrape worker for ID-only URLs (Questys `File.ashx?id=N` carries no extension): OLE → `.doc`, ZIP → `.docx`, `II*\\x00`/`MM\\x00*` → `.tif`\n- 4 new tests + v3.2.4 regression guard = 5/5 green\n\n**v3.2.0 → v3.2.4 — Operator UI parity + Drupal extraction + audit-consistency tests**\n\n- **v3.2.0**: 5 new DB-backed list/query endpoints (`/documents`, `/anomalies`, `/analyses`, `/jurisdictions`, `/synthesis/aggregates`) + 4 listing pages swapped from browser localStorage to backend fetches. Closes a year-old gap where webhook-ingested data was invisible in the operator UI.\n- **v3.2.1**: Suspense wrapper for `useSearchParams()` (Next.js 15 static-export compatibility) — unblocked desktop builds.\n- **v3.2.2 / v3.2.3**: 15-test audit-consistency suite (Test A determinism + Test B MAS faithfulness vs raw SQL + Test C RAIA subphase contract). CRLF-aware fixture-size assertions for Linux CI parity.\n- **v3.2.4**: Semantic-container HTML extraction (`\u003cmain\u003e` → `\u003carticle\u003e` → `[role=\"main\"]`) — fixed Drupal sites where the v3.1.1 generic strip missed `\u003cdiv\u003e`-wrapped nav cruft and drowned the article body.\n\n**v3.1.0 → v3.1.1 — Tier-2 fetcher + HTML ingest**\n\n- **v3.1.0**: `curl_cffi` Chrome impersonation as a Tier-2 fallback for HTTP 403/429/OSError — defeats Akamai/Cloudflare bot mitigation that pre-v3.1.0 made entire jurisdictions unreachable.\n- **v3.1.1**: HTML (`.html`/`.htm`) ingestion branch + filename-suffix logic respecting the recognised types. Unblocked WordPress-based jurisdictions.\n\n**v3.0.0 → v3.0.5 — Live automation goes online**\n\n- **v3.0.0**: Production multi-platform desktop release (Windows / macOS arm64 / macOS Intel / Linux AppImage) — Oraculus monogram, malachite hero, RAIA template hardening, mesh-job zombie reconciliation.\n- **v3.0.2**: Backend-side URL scraping via `POST /webhook/scrape-and-ingest` — solves Cloudflare TLS-fingerprint blocks that the n8n HTTP node couldn't bypass.\n- **v3.0.3 / v3.0.4**: `POST /webhook/scrape-and-ingest-async` for fire-and-forget downloads + `_DOWNLOAD_SEMAPHORE(4)` concurrency cap + widened OSError catch for `RemoteDisconnected`.\n- **v3.0.5**: RAIA pattern-detection polish — `all_anomalies` field surfaces complete shared-finding sets to pattern detectors (previously capped at the top-10 slice).\n\nOlder v2.x release cycles (Cross-Entity Analysis Protocol, Mineral Calibration, JARVIS HUD, gemstone palette, OCR coverage) are captured in [CHANGELOG.md](CHANGELOG.md) with full track-by-track detail.\n\n## Empirical State (live as of v3.4.0)\n\nODIA has been live-ingested across 5 California jurisdictions on 4 distinct CMS platforms:\n\n| Jurisdiction | CMS | Docs | Anomalies | Critical | Avg Score |\n|---|---|---|---|---|---|\n| TCDA (DA narratives) | WordPress | 660 | 102 | 0 | 0.989 |\n| Tulare County (BOS) | Questys CMX + Drupal | 95 | 119 | 8 | 0.909 |\n| Visalia | CivicPlus | 85 | 80 | 5 | 0.932 |\n| **Dinuba** | Upload audit | **62** | **277** | **49** | — |\n| Porterville | Revize | 8 | 23 | 2 | 0.766 |\n| **TOTAL** | **4 CMS + upload** | **910** | **601** | **64** | — |\n\n**Dinuba** is the highest critical-anomaly-density corpus yet — 49 critical findings across 62 documents, driven by signature gaps on formal instruments and significant procurement irregularities.\n\n**Cross-jurisdiction RAIA synthesis** across all 5 jurisdictions surfaces **1 universal pattern at 1.00 confidence** (`admin:missing-final-action` — fires in all 5 jurisdictions) and a growing set of shared patterns including: signature-unsigned-instrument, scope-significant-expansion, vendor-convergence:sole-source, governance:sole-source-without-justification, fiscal:amount-without-appropriation, procurement:sole-source-without-gov-code-citation. **Tulare County-exclusive critical findings** (`grant:jag-without-anti-supplanting` citing 34 U.S.C. § 10152, `admin:retroactive-authorization` × 29) are surfaced exclusively by the BOS corpus and now include embedded statute text via the USC legal resolver.\n\n## What's New in v2.7.x\n\nThe v2.7 release line moved O.D.I.A. from a developer tool into a\nproduction-grade desktop application for civic-accountability operators.\n\n**v2.7.8** — TypeScript fix on top of v2.7.7's gemstone palette\npropagation: `\u003cAppLink\u003e` and SVG icon components now accept the `style`\nprop required by the new CSS-variable-based palette. v2.7.7's tag failed\nCI at the typecheck step; v2.7.8 supersedes it with the same gem palette.\n\n**v2.7.7 — Gemstone palette (Y1–Y5)**\n- Vibrant neon emerald + matte gold dual-edge tokens propagated platform-wide\n- Crystallized facet panel utility (`.gem-panel-faceted` — 12-vertex quartz\n  silhouette via clip-path)\n- Sidebar, topbar, mobile bottom-tab bar, base components, every Dashboard\n  card restyled\n- Severity strip on Dashboard rewired to the live `/api/v1/dashboard/summary`\n  endpoint (was reading from a dead client-side store)\n\n**v2.7.6 — Functional pass (X1–X5)**\n- New dashboard summary endpoint backing the Analysis Summary card\n- Frozen-aware jurisdiction discovery + \"Seed Example Jurisdictions\" trigger\n  so RAIA Synthesis works on a fresh desktop install\n- Legistar retrieval bridges into the upload-staging store (downloads now\n  appear in the Upload page's \"files ready\" table)\n- Audit pipeline records `MeshExecutionJob` rows so the Orchestrator\n  timeline reflects actual work\n- Initial gemstone hero POC\n\n**v2.7.5 — Manual Triggers wired (W1–W4)**\n- ODIA-native `/api/v1/triggers/*` route family bypasses the n8n token\n  gate so the Manual Triggers panel works out of the box\n- Ingest tab consolidated into Upload (legacy redirect preserved)\n- CCOPS Compliance scorecard on HUD primitives\n\n**v2.7.4 — Quality polish (V1–V5)**\n- Database initialization at startup (closes silent-degrade gap)\n- Dynamic version pill on the sidebar\n- Tri-state UX on Orchestrator executions\n- Three-state automation tile (`READY` / `OFFLINE` / `NOT CONFIGURED`)\n\n**v2.7.3 — Audit-fix sprint (D1–D8)**\n- MAS narrative templates\n- General-path SeenHash deduplication\n- Fail-loud PDF extraction (no more silent text-extraction failures)\n- Orchestrator page rewrite\n\nSee [docs/PHASES.md](docs/PHASES.md) for the full version history.\n\n---\n\n## Features\n\n- **Ten-detector analysis engine** — fiscal, constitutional, surveillance,\n  procurement, signature, scope, governance, administrative integrity, grant\n  compliance (JAG / COPS / Edward Byrne anti-supplanting), and **cross-entity\n  reference detection** (D-13, Cross-Entity Analysis Protocol V1.0); all\n  executed locally, no cloud calls\n- **Multi-format ingestion** — PDF (with OCR fallback), XML, JSON, TXT;\n  drag-and-drop or programmatic\n- **Legistar retrieval** — pull legislative documents directly from any of 50\n  preconfigured city portals (configurable for any city using the Legistar\n  platform)\n- **Multi-jurisdiction analysis** — compare anomaly patterns across multiple\n  jurisdictions in one run; detect vendor-playbook replication, shared\n  procurement irregularities, regional governance gaps\n- **CCOPS compliance scorecard** — automated assessment against all 11 ACLU\n  CCOPS model bill mandates with per-mandate compliance status\n- **Temporal pattern detection** — contract lineage reconstruction, six\n  evolution-pattern detectors, timeline visualization\n- **RAG query engine** — multi-source retrieval across documents, findings,\n  analysis results, and legal reference data with LLM-ready context building\n- **Legal reference dataset** — 255 searchable terms (Bouvier 1856, Anderson\n  1889, Cornell Wex, Latin maxims), 81 SCOTUS / federal cases, 35 extracted\n  holdings, superseded-doctrine tracking; all public domain / open access\n- **Multi-agent orchestration** — six-stage task graph (ingestion → analysis\n  → anomaly → synthesis → database → interface) with dependency resolution\n  and execution recording\n- **n8n integration** — token-gated webhook surface (`/api/v1/webhook/*`)\n  for scheduled scrapes, deadline alerts, and external triggers; bundled\n  reference workflows\n- **Manual Triggers panel** — RAIA cross-jurisdictional synthesis, CPRA\n  deadline checking, jurisdiction seeding from inside the desktop UI; no\n  n8n required\n- **REST API** — FastAPI backend with 50+ endpoints across analysis,\n  orchestration, governance, compliance, retrieval, upload, audit,\n  triggers, webhooks, automation, and dashboard surfaces\n- **Modern frontend** — Next.js 14 + Electron desktop with the **gemstone\n  HUD palette** (smoke-spine background, matte gold + neon emerald dual-edge\n  cuts, crystallized quartz-facet panels)\n- **PWA support** — installable as a Progressive Web App on mobile with\n  responsive layout, camera capture, OCR image upload, navigator.share()\n- **Auth + workspace** — JWT + bcrypt with single-user fallback; workspace\n  package with chain-of-custody `AuditLog`\n- **Provenance tracking** — SHA-256 hashing on every document with\n  fingerprinting, lineage, and litigation-grade chain-of-custody export\n- **Privacy-first** — all processing is local; no telemetry, no cloud\n  dependency, no required LLM API keys, no internet required after install\n\n---\n\n## Architecture\n\nTwo source packages under `src/`:\n\n```\nsrc/\n├── oraculus_di_auditor/   # Main platform (192+ modules)\n│   ├── analysis/          # Nine anomaly detectors\n│   ├── ingestion/         # PDF / XML / JSON / TXT parsing + OCR fallback\n│   ├── orchestrator/      # Multi-agent task graph (Phase 5/8)\n│   ├── governor/          # Policy enforcement, security gatekeeper (Phase 9)\n│   ├── interface/         # FastAPI app + 14 route modules\n│   ├── reporting/         # Pydantic models, Jinja2 templates, plain-language\n│   │                      # translator, evidence-packet ZIP generator\n│   ├── rag/               # Retrieval engine, context builder, prompt router\n│   ├── legal/             # Case law builder, definition extractor\n│   ├── adapters/          # CCOPS adapter (11 mandates), Atlas adapter,\n│   │                      # Legistar adapter (50 cities), compliance engine\n│   ├── temporal/          # Contract lineage, evolution detectors, timeline\n│   ├── multi_jurisdiction/# Registry, runner, pattern detector, comparative\n│   │                      # report generator\n│   ├── auth/              # User / Session / JWT / bcrypt\n│   ├── workspace/         # Workspace, member, AuditLog (chain-of-custody)\n│   ├── db/                # SQLAlchemy models, CRUD, session\n│   ├── raia/              # Recursion Analysis Investigative Audit service\n│   └── ...                # Higher-phase engines (see docs/PHASES.md)\n└── oraculus/              # Legislative scaffold (loaders, provenance)\n```\n\nFull architecture details: [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)\nPhase-by-phase engine reference: [docs/PHASES.md](docs/PHASES.md)\n\n---\n\n## API Endpoints\n\n50+ endpoints across the following surfaces (FastAPI auto-docs at\n`/docs` and `/redoc`):\n\n### Core analysis\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/v1/health` | System health + version |\n| `POST` | `/api/v1/analyze` | Analyze a single document |\n| `GET` | `/api/v1/detectors` | List registered detectors + anomaly types |\n\n### Upload + audit pipeline\n\n| Method | Path | Description |\n|---|---|---|\n| `POST` | `/api/v1/upload` | Upload a single PDF / TXT / JSON / XML |\n| `POST` | `/api/v1/upload/batch` | Multi-file upload |\n| `POST` | `/api/v1/upload/image` | Image upload + OCR (JPEG / PNG) |\n| `GET` | `/api/v1/upload/files` | List staged files |\n| `POST` | `/api/v1/audit/run` | Start an audit job |\n| `GET` | `/api/v1/audit/status/{job_id}` | Poll progress |\n| `GET` | `/api/v1/audit/results/{job_id}` | Retrieve full results |\n| `GET` | `/api/v1/audit/export/{job_id}` | Export Markdown / HTML / PDF / DOCX |\n| `GET` | `/api/v1/audit/evidence-packet/{job_id}` | Download chain-of-custody ZIP |\n\n### Dashboard\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/v1/dashboard/summary` | Aggregated counters for the home page |\n| `POST` | `/api/v1/dashboard/seed-jurisdictions` | Copy bundled examples to user dir |\n\n### Orchestrator + Governor\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/v1/orchestrator/task-graph` | Static six-agent topology |\n| `GET` | `/api/v1/orchestrator/executions` | Recent MeshExecutionJob rows |\n| `GET` | `/api/v1/orchestrator/status` | Live agent / task counters |\n| `POST` | `/api/v1/orchestrator/run` | Multi-document orchestration |\n| `GET` | `/api/v1/governor/state` | Pipeline health summary |\n| `POST` | `/api/v1/governor/validate` | Validate pipeline (quick or deep) |\n\n### Manual Triggers (no auth, no n8n required)\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/v1/triggers/cpra-deadlines/{72h\\|7d\\|30d}` | Closing CPRA requests |\n| `POST` | `/api/v1/triggers/raia-synthesize-all` | Cross-jurisdictional synthesis |\n| `POST` | `/api/v1/triggers/provenance-chain-export` | Litigation-grade export (501 stub at L0) |\n\n### n8n webhooks (token-gated; require `ODIA_WEBHOOK_TOKEN`)\n\n| Method | Path | Used by |\n|---|---|---|\n| `GET` | `/api/v1/webhook/health` | Liveness probe (no token) |\n| `POST` | `/api/v1/webhook/ingest-and-analyze` | WF-001 CivicPlus scraper |\n| `POST` | `/api/v1/webhook/batch-ingest` | WF-002 nightly batch |\n| `GET` | `/api/v1/webhook/status/{job_id}` | Batch-job status |\n| `POST` | `/api/v1/webhook/synthesize` | WF-010 RAIA synthesis distributor |\n\n### Other\n\n| Method | Path | Description |\n|---|---|---|\n| `GET` | `/api/v1/retrieve/cities` | List 50 known Legistar cities |\n| `POST` | `/api/v1/retrieve/legistar` | Start a Legistar retrieval job |\n| `POST` | `/api/v1/compliance/assess` | CCOPS scorecard generation |\n| `GET` | `/api/v1/compliance/mandates` | List all 11 CCOPS mandates |\n| `POST` | `/api/v1/rag/query` | RAG query with LLM-ready context |\n| `POST` | `/api/v1/cpra/deadlines-within/{window}` | CPRA deadline range query |\n\nFull automation routes (`/api/v1/automation/*`) proxy to n8n when\n`N8N_API_KEY` is configured. See\n[docs/AUTOMATION_SETUP.md](docs/AUTOMATION_SETUP.md) for setup.\n\n---\n\n## Automation (n8n)\n\nO.D.I.A. ships with a token-gated webhook surface for driving automated\ningestion, analysis, and cross-jurisdiction synthesis from\n[n8n](https://n8n.io/) workflows.\n\n**For end users:** the desktop install includes a **Manual Triggers** panel\non the Automation tab that works out of the box without n8n — see\n[docs/AUTOMATION_SETUP.md](docs/AUTOMATION_SETUP.md) Level 0.\n\n**For automated / scheduled workflows** (CivicPlus auto-ingest, CPRA\ndeadline alerts, nightly batch scrapes), bring up the optional n8n stack:\n\n```bash\ncp .env.example .env\n# Edit .env, set ODIA_WEBHOOK_TOKEN / N8N_ENCRYPTION_KEY / POSTGRES_PASSWORD\n#   python -c \"import secrets; print(secrets.token_urlsafe(32))\"\n\ndocker compose -f docker-compose.yml -f docker-compose.n8n.yml up -d\n```\n\nThen:\n\n- n8n editor → http://localhost:5678 (basic-auth from `.env`)\n- Backend webhook health → `curl -H \"X-ODIA-Webhook-Token: $ODIA_WEBHOOK_TOKEN\" http://localhost:8000/api/v1/webhook/health`\n- Reference workflows → `data/n8n-workflows/bundle.json` (import via n8n\n  UI; activate per-jurisdiction after review — **all ship INACTIVE** by\n  design)\n\nIf `ODIA_WEBHOOK_TOKEN` is unset, the webhook route surface refuses to\nregister and logs an error — misconfigured deployments fail loud rather\nthan silently exposing an open pipeline.\n\nComplete walkthrough with troubleshooting:\n[docs/AUTOMATION_SETUP.md](docs/AUTOMATION_SETUP.md)\n\n---\n\n## Audit Triage Pipeline\n\nFor manual audit workflows with chain-of-custody tracking:\n\n```bash\n# Flag a document\npython scripts/triage.py \\\n  --doc-id DOC001 --path /path/to/document.pdf \\\n  --flag \"Missing certification\" --severity high \\\n  --category doj_certification --author \"Your Name\"\n\n# Generate audit report\npython scripts/render_report.py --output reports/audit_report.md\n\n# Generate GitHub issue drafts for high/critical findings\npython scripts/auto_issue_generator.py --severity high --severity critical\n```\n\nSee [QUICKSTART.md](QUICKSTART.md) for the full triage workflow.\n\n---\n\n## Multi-Jurisdiction Analysis\n\nCompare anomaly patterns across multiple jurisdictions in a single run:\n\n```bash\npython scripts/run_multi_audit.py \\\n    --config-dir config/multi_jurisdiction \\\n    --source-dir data/multi_jurisdiction \\\n    --output reports/multi_jurisdiction \\\n    --verbose\n```\n\nEach jurisdiction needs a config directory under `config/multi_jurisdiction/\u003cid\u003e/`\nwith a `jurisdiction.json` file. Documents go in `data/multi_jurisdiction/\u003cid\u003e/`.\n\n**What it detects across jurisdictions:**\n- Vendor playbook replication — same anomaly patterns from the same vendor\n  across multiple jurisdictions\n- Procurement parallels — shared sole-source justifications or timeline\n  irregularities\n- Regional governance gaps — common policy absences across a geographic cluster\n\n**Output:** JSON + Markdown comparative reports with risk ranking and\nrecommendations.\n\nA synthetic sample dataset covering three California jurisdictions is included\nin `data/multi_jurisdiction/`. See\n[docs/MULTI_JURISDICTION.md](docs/MULTI_JURISDICTION.md) for full setup and\nconfiguration guidance.\n\n---\n\n## Compliance Assessment\n\nEvaluate surveillance technology procurement against the ACLU CCOPS\n(Community Control Over Police Surveillance) framework:\n\n```bash\npython scripts/run_compliance_check.py \\\n  --config-dir config/ --source data/sources/ \\\n  --output reports/compliance/\n```\n\nMaps ODIA detector findings to all 11 CCOPS model bill mandates and produces a\n`ComplianceScorecard` with per-mandate status (`compliant`, `non_compliant`,\n`partial`, `unknown`), overall risk level, and specific recommendations. Also\navailable via `POST /api/v1/compliance/assess` in the API and the **Compliance**\ntab in the desktop UI.\n\nSee [docs/COMPLIANCE_FRAMEWORK.md](docs/COMPLIANCE_FRAMEWORK.md) for the full\nmandate mapping, risk levels, and programmatic usage guide.\n\n---\n\n## Configuration\n\n```yaml\n# config/defaults.yaml\npdf_storage: \"external\"          # Keep PDFs outside repo\nredaction:\n  enabled: false                 # Manual review required before publishing\n  auto_detect_pii: true\nollama:\n  host: \"localhost\"\n  port: 11434\n  default_model: \"llama3-small\"  # Optional: local LLM evaluation\n```\n\nCorpus configuration: copy `config/corpus_manifest.example.json` to\n`config/corpus_manifest.json` and set your jurisdiction's data sources.\n\nMulti-jurisdiction configuration on the desktop install: use the **Seed\nExample Jurisdictions** trigger on the Automation tab (or\n`POST /api/v1/dashboard/seed-jurisdictions`), then edit the resulting JSON\nfiles in your user-writable config dir (`%APPDATA%\\ODIA\\config\\multi_jurisdiction\\`\non Windows, `~/Library/Application Support/ODIA/config/multi_jurisdiction/` on\nmacOS, `~/.local/share/odia/config/multi_jurisdiction/` on Linux).\n\n---\n\n## Development\n\n```bash\n# Install with dev dependencies\npip install -e \".[dev]\"\n\n# Run tests with coverage\npytest --cov=src/oraculus --cov=src/oraculus_di_auditor --cov-report=term-missing\n\n# Format and lint\nblack src tests\nruff check src tests\n\n# Frontend dev server (hot reload)\ncd frontend \u0026\u0026 npm install \u0026\u0026 npm run dev\n```\n\nAll anomaly detectors return structured results:\n```python\n{\n    \"id\":       str,               # stable dot-namespaced identifier\n    \"issue\":    str,               # human-readable description\n    \"severity\": \"low|medium|high|critical\",\n    \"layer\":    str,               # detector name\n    \"details\":  dict,              # structured evidence\n}\n```\n\nSee [docs/developer-setup.md](docs/developer-setup.md) for full setup\ninstructions, [docs/development-workflow.md](docs/development-workflow.md)\nfor the contribution flow, and [docs/RELEASING.md](docs/RELEASING.md) for\nthe release runbook (six version-string locations to bump per release).\n\n---\n\n## Privacy \u0026 Security\n\n- **No automatic external data uploads.** All analysis is local. The only\n  outbound calls are the optional Legistar fetch (to public city portals)\n  and any actions you explicitly configure in n8n workflows.\n- **No telemetry.** O.D.I.A. never phones home with usage data.\n- **No required LLM API keys.** OpenAI / Anthropic integration is opt-in\n  for the RAG layer only and is not required for any other feature.\n- **PII redaction is NOT automatic** — manual review required before\n  publishing reports.\n- **Original PDFs stored externally by default** (`config/defaults.yaml`).\n- **All manifests include chain-of-custody timestamps and SHA-256 checksums.**\n- **Webhook endpoints fail loud** if the token isn't configured (refuse to\n  register rather than silently exposing an open pipeline).\n- **Consult qualified legal counsel before public disclosure of audit findings.**\n\nSee [docs/DATA_POLICY.md](docs/DATA_POLICY.md),\n[docs/DATA_PROVENANCE.md](docs/DATA_PROVENANCE.md), and\n[compliance_checklist.md](compliance_checklist.md).\n\n---\n\n## Documentation\n\nUser-facing:\n- [QUICKSTART.md](QUICKSTART.md) — 60-second demo + your first audit\n- [docs/AUTOMATION_SETUP.md](docs/AUTOMATION_SETUP.md) — desktop install through optional n8n stack, written for non-developers\n- [docs/MULTI_JURISDICTION.md](docs/MULTI_JURISDICTION.md) — comparative analysis across cities\n- [docs/COMPLIANCE_FRAMEWORK.md](docs/COMPLIANCE_FRAMEWORK.md) — CCOPS mandate mapping\n- [docs/LEGAL_REFERENCE.md](docs/LEGAL_REFERENCE.md) — legal reference dataset\n- [docs/OCR_SETUP.md](docs/OCR_SETUP.md) — OCR (Tesseract / Poppler) setup\n- [docs/RAG_SETUP.md](docs/RAG_SETUP.md) — RAG query engine setup\n\nDeveloper-facing:\n- [docs/developer-setup.md](docs/developer-setup.md) — full dev environment\n- [docs/development-workflow.md](docs/development-workflow.md) — contribution flow\n- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — system architecture\n- [docs/PHASES.md](docs/PHASES.md) — phase-by-phase engine reference\n- [docs/RELEASING.md](docs/RELEASING.md) — release runbook\n- [docs/database-design.md](docs/database-design.md) — schema reference\n\n---\n\n## License\n\nCopyright © 2025 Synthetic Technology Revolution — MIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntechrev%2Fodia","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntechrev%2Fodia","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntechrev%2Fodia/lists"}