/ ARCHITECTURE.md
ARCHITECTURE.md
1 # ARGUS-AI Architecture 2 3 ## Open Core Strategy 4 5 ARGUS follows an **Open Core** model. This repository is the open-source layer. 6 7 ``` 8 ┌──────────────────────────────────────────────────────────────────────┐ 9 │ ARGUS Platform (Commercial) │ 10 │ │ 11 │ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ 12 │ │ Orchestrator │ │ Prompt Optimizer │ │ Self-Healing Loop │ │ 13 │ │ Agent │ │ (Auto-tune) │ │ (Closed-Loop) │ │ 14 │ └─────────────────┘ └──────────────────┘ └──────────────────────┘ │ 15 │ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ 16 │ │ LLM-as-Judge │ │ Async Batch │ │ Multi-Model │ │ 17 │ │ Evaluation │ │ Processing │ │ Variance Analysis │ │ 18 │ └─────────────────┘ └──────────────────┘ └──────────────────────┘ │ 19 │ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ 20 │ │ Dashboard UI │ │ Team Management │ │ SOC2/HIPAA │ │ 21 │ │ │ │ │ │ Compliance │ │ 22 │ └─────────────────┘ └──────────────────┘ └──────────────────────┘ │ 23 ├──────────────────────────────────────────────────────────────────────┤ 24 │ argus-ai (Open Source - This Repo) │ 25 │ │ 26 │ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ 27 │ │ G-ARVIS Scorer │ │ 3-Line SDK │ │ Threshold Monitor │ │ 28 │ │ (6 Dimensions) │ │ init/evaluate │ │ + Sliding Window │ │ 29 │ └─────────────────┘ └──────────────────┘ └──────────────────────┘ │ 30 │ ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────┐ │ 31 │ │ Agentic Metrics│ │ Exporters │ │ Provider Wrappers │ │ 32 │ │ ASF/ERR/CPCS │ │ Prom/OTEL/CLI │ │ Anthropic/OpenAI │ │ 33 │ └─────────────────┘ └──────────────────┘ └──────────────────────┘ │ 34 └──────────────────────────────────────────────────────────────────────┘ 35 ``` 36 37 ## Data Flow 38 39 ``` 40 User LLM Call 41 │ 42 ▼ 43 ┌─────────────┐ ┌──────────────────────────────────────────────┐ 44 │ ArgusClient │────▶│ GarvisScorer │ 45 │ .evaluate() │ │ │ 46 └─────────────┘ │ ┌───────────┐ ┌──────────┐ ┌───────────┐ │ 47 │ │Groundednes│ │ Accuracy │ │Reliability│ │ 48 │ │ Scorer │ │ Scorer │ │ Scorer │ │ 49 │ └─────┬─────┘ └────┬─────┘ └─────┬─────┘ │ 50 │ ┌─────┴─────┐ ┌────┴─────┐ ┌─────┴─────┐ │ 51 │ │ Variance │ │Inference │ │ Safety │ │ 52 │ │ Scorer │ │CostScorer│ │ Scorer │ │ 53 │ └─────┬─────┘ └────┬─────┘ └─────┬─────┘ │ 54 │ └────────┬────┘ │ │ 55 │ ▼ │ │ 56 │ Weighted Composite ◄────────┘ │ 57 └──────────────────┬───────────────────────────┘ 58 │ 59 ▼ 60 ┌──────────────────────────────────────┐ 61 │ ThresholdMonitor │ 62 │ ┌────────────┐ ┌────────────────┐ │ 63 │ │ Point-in- │ │ Sliding Window │ │ 64 │ │ Time Check │ │ Breach Detect │ │ 65 │ └──────┬─────┘ └───────┬────────┘ │ 66 │ └──────┬─────────┘ │ 67 │ ▼ │ 68 │ Alert Rules │ 69 └────────────────┬─────────────────────┘ 70 │ 71 ┌────────────────┼────────────────┐ 72 ▼ ▼ ▼ 73 ┌──────────┐ ┌──────────────┐ ┌────────────┐ 74 │ Console │ │ Prometheus │ │ OpenTelemetry│ 75 │ Exporter │ │ Exporter │ │ Exporter │ 76 └──────────┘ └──────────────┘ └────────────┘ 77 ``` 78 79 ## Module Structure 80 81 ``` 82 src/argus_ai/ 83 ├── __init__.py # Public API surface (3-line SDK) 84 ├── types.py # Pydantic data models 85 ├── scoring/ 86 │ ├── garvis.py # Composite scorer + weight profiles 87 │ ├── metrics.py # 6 individual dimension scorers 88 │ └── agentic.py # ASF, ERR, CPCS metrics 89 ├── sdk/ 90 │ ├── client.py # ArgusClient + init() 91 │ └── decorators.py # @argus_evaluate decorator 92 ├── monitoring/ 93 │ ├── thresholds.py # ThresholdMonitor + sliding window 94 │ └── alerts.py # AlertRule + severity definitions 95 ├── exporters/ 96 │ ├── prometheus.py # Prometheus gauges/histograms 97 │ └── otel.py # OpenTelemetry metrics 98 └── integrations/ 99 ├── anthropic.py # InstrumentedAnthropic wrapper 100 └── openai.py # InstrumentedOpenAI wrapper 101 ``` 102 103 ## Design Principles 104 105 1. **Zero-dependency core**: Only pydantic, numpy, structlog required 106 2. **Sub-millisecond scoring**: Heuristic scorers run in <5ms per evaluation 107 3. **Extensible**: Plugin architecture for custom scorers and exporters 108 4. **Type-safe**: Full mypy strict mode compliance 109 5. **Production-first**: Structured logging, Prometheus/OTEL export, alert callbacks 110 111 ## What's NOT in Open Source (ARGUS Platform) 112 113 The following capabilities are proprietary and not included: 114 115 - **Autonomous correction loop**: The orchestrator agent that automatically 116 fixes degraded LLM outputs 117 - **Prompt optimizer**: Auto-tunes prompts based on G-ARVIS score trends 118 - **LLM-as-judge evaluation**: Model-based quality scoring (vs heuristic) 119 - **Multi-run variance analysis**: Temperature sweep, prompt perturbation tests 120 - **Async batch processing**: High-throughput parallel evaluation pipeline 121 - **Dashboard UI**: Real-time G-ARVIS visualization and team management 122 - **Compliance reporting**: SOC2/HIPAA audit trail generation