feat: comprehensive docs, unit tests, docker-compose app services

- Add scheduler and ingestion unit tests (test_scheduler_unit.py, test_ingestion_unit.py) - Add all 13 app services + dashboard to docker-compose.yml - Add full documentation suite: API reference, Helm reference, Docker deployment guide, 3 architecture diagrams (K8s, Docker Compose, data pipeline), AI agent guide, backup/restore guide, observability/metrics reference, per-service docs - Add intelligence pipeline deep-dive docs with Mermaid diagrams - Update README with documentation index and links - Add specs for comprehensive-quality-docs, intelligence-pipeline-deep-dive, sanitized-pipeline-docs
2026-04-22 02:56:41 +00:00
parent f251c53f92
commit 88ad1e8d99
57 changed files with 13318 additions and 51 deletions
@@ -0,0 +1,80 @@
+# Recommendation Generation Flow
+
+```mermaid
+flowchart TD
+    Q_REC["app:queue:recommendation"] -->|"lpop"| WORKER["Recommendation Worker\nservices/recommendation/main.py"]
+
+    WORKER --> FETCH["Fetch TrendSummary\nfrom trend_windows\nfor entity + window"]
+
+    FETCH --> SUPP
+
+    subgraph SUPP["Data Quality Suppression\nservices/recommendation/suppression.py"]
+        S1["extraction confidence < 0.40?"]
+        S2["evidence staleness > 168h?"]
+        S3["source diversity < 1 type?"]
+        S4["extraction failure rate > 50%?"]
+        S5["valid documents < 2?"]
+        S6["data quality score < 0.30?"]
+        S7["Macro-only signal?\nevaluate_macro_only_suppression()"]
+        S8["Pattern-only signal?\nevaluate_pattern_only_suppression()"]
+    end
+
+    SUPP -->|"Any check fails:\nsuppressed = true\nmode → informational"| ELIG
+    SUPP -->|"All checks pass"| ELIG
+
+    subgraph ELIG["Eligibility Evaluation\nservices/recommendation/eligibility.py"]
+        direction TB
+        G["Gate Checks"]
+        G1["confidence ≥ 0.35"]
+        G2["strength ≥ 0.10"]
+        G3["contradiction ≤ 0.60"]
+        G4["evidence ≥ 2"]
+        G5["direction ≠ neutral"]
+        G --> G1 & G2 & G3 & G4 & G5
+
+        G1 & G2 & G3 & G4 & G5 --> ACT["Action Mapping"]
+        ACT --> A1["ACT: positive + strength ≥ 0.25"]
+        ACT --> A2["DEFER: negative + strength ≥ 0.25"]
+        ACT --> A3["MONITOR: directional + confidence ≥ 0.50"]
+        ACT --> A4["OBSERVE: otherwise"]
+
+        A1 & A2 & A3 & A4 --> MODE["Mode Escalation"]
+        MODE --> M1["informational\n(default for MONITOR/OBSERVE)"]
+        MODE --> M2["simulation_eligible\nconfidence ≥ 0.50"]
+        MODE --> M3["production_eligible\nconfidence ≥ 0.70\ncontradiction ≤ 0.25\nevidence ≥ 5"]
+    end
+
+    ELIG --> SIZING
+
+    subgraph SIZING["Commitment Sizing\nservices/recommendation/eligibility.py"]
+        PS1["base = 1% allocation pool"]
+        PS2["scale by confidence × strength\nup to 10% max"]
+        PS3["contradiction penalty\n−0.5 × contradiction_score"]
+        PS4["evidence count penalty\n< 3 docs → ×0.5\n< 5 docs → ×0.75"]
+    end
+
+    SIZING --> THESIS
+
+    subgraph THESIS["Thesis Generation"]
+        TH1["Deterministic thesis\nassembled from trend data"]
+        TH2["Optional LLM rewrite\nthesis-rewriter agent\nservices/recommendation/thesis_llm.py"]
+        TH1 --> TH2
+    end
+
+    THESIS --> RISK
+
+    subgraph RISK["Risk Classification"]
+        RC1["low"]
+        RC2["moderate"]
+        RC3["high"]
+        RC4["very_high"]
+    end
+
+    RISK --> PERSIST
+
+    subgraph PERSIST["Persistence — PostgreSQL"]
+        P1["recommendations"]
+        P2["recommendation_evidence"]
+        P3["risk_evaluations"]
+    end
+```