# Self-Learning Baseline

This document fixes the current baseline for Logos ADK as a self-improving platform.

The goal is to separate:
- what is already implemented,
- what is runtime-connected,
- what exists only as manual/operator tooling,
- and what is still missing.

This is the baseline for the next implementation phases:
- `LearningCoordinator`
- `SelfLearningLoop`
- automatic prompt candidate generation
- learned reward scoring
- persistent continuous evaluation and rollback policies

## Current Capability Map

### `logos_adk/learning/feedback_api.py`

Purpose:
- capture `FeedbackRecord` and `OutcomeRecord`
- resolve run context by `run_id` or `trace_id`
- preserve linkage to `session_id`, `workspace_id`, `prompt_version`, `model`, `config_fingerprint`

Implemented:
- feedback capture: thumbs, numeric ratings, edited answers, suggestion outcomes
- outcome capture: conversion, resolution, CTR, reply rate, escalation, human takeover
- trace-linked write path into `LearningStore`
- memory-learning sync through `MemoryLearningTarget`

Runtime-connected:
- yes, through `/feedback` and `/outcomes`
- yes, for memory sync after feedback capture

Manual-only:
- none in the capture layer itself

Missing:
- centralized coordinator for retrieval/model-routing/tool/workflow sync
- non-HTTP orchestration path for all online updates
- idempotent multi-subscriber sync policy by `trace_id`

### `logos_adk/learning/optimizer.py`

Purpose:
- generate prompt recommendations from production failures
- rank prompt candidates offline
- guard promotion against regressions

Implemented:
- `RecommendationEngine` for prompt patch suggestions from recurring failures
- `PromptOptimizer.evaluate_candidates(...)`
- `PromptOptimizer.create_optimized_version(...)`
- `PromptPolicyGuard` for latency/cost/safety regression checks
- live experiment reporting from captured runs

Runtime-connected:
- yes, through prompt learning HTTP/CLI/operator surface
- yes, through prompt registry and prompt experiments

Manual-only:
- candidate generation is still operator-supplied
- deployment decisions still require explicit invocation

Missing:
- automatic candidate generation from patterns/corrections/reflection lessons
- orchestration loop that collects failures, evaluates candidates, and deploys/promotes them
- persistent audit trail for why a candidate was rejected or promoted across the whole loop

### `logos_adk/learning/evaluation/runner.py` and `logos_adk/learning/evaluation/engine.py`

Purpose:
- continuous evaluation and regression control from production-derived data

Implemented:
- production regression datasets from bad runs
- judge disagreement tracking
- scorecards for weekly deltas
- champion/challenger comparison
- continuous eval runner with in-process job scheduling

Runtime-connected:
- yes, through operator HTTP/CLI surface
- yes, through quality history persistence

Manual-only:
- jobs are registered and managed explicitly
- remediation logic after regression is still manual/operator-driven

Missing:
- richer multi-tenant scheduling and external worker execution
- stronger alert delivery integrations outside the in-process/operator path
- broader end-to-end automation above the current closed-loop building blocks

### `logos_adk/learning/improvement/`

Purpose:
- provide true-improvement primitives above raw learning signals

Implemented:
- `RewardModel` heuristic unified scorer
- `PolicyLearner` for routing/retrieval/tool/fallback recommendations
- `TrainingExportBuilder` for `SFT`, `DPO`, and `RL`
- `CriticReviserLoop`
- `ReflectionMemory`
- `PatternMiner`

Runtime-connected:
- yes, through operator HTTP/CLI surface for reward scores, policy, training export, reflection lessons, failure patterns
- yes, through action-layer endpoints for mining lessons, exporting policy, running critic/reviser, and reward trends

Manual-only:
- policy output is still recommendation/export, not automatic runtime enforcement
- critic/reviser is explicitly invoked, not part of default answer loop
- reflection lesson mining is an operator action, not scheduled orchestration

Missing:
- orchestration layer that chains failure collection -> mining -> candidate generation -> evaluation -> deploy/rollback
- learned reward scorer interface and preference model
- prompt evolution generator
- rollback and promotion automation

## Status Matrix

| Area | Implemented | Runtime-connected | Manual-only | Missing |
|---|---|---:|---:|---:|
| Feedback and outcomes | Yes | Yes | No | Coordinator-driven multi-sync |
| Memory sync | Yes | Yes | No | Unified coordinator ownership |
| Retrieval learning | Yes | Partially | Yes | Centralized online sync, automatic loop |
| Model routing learning | Yes | Partially | Yes | Centralized online sync, automatic loop |
| Tool/workflow learning | Yes | Partially | Yes | Coordinator + policy automation |
| Prompt optimization | Yes | Partially | Yes | automatic candidate generation |
| Prompt registry/experiments | Yes | Yes | Yes | promotion/rollback automation |
| Reward scoring | Yes | Yes | Yes | learned scorer interface/model |
| Reflection memory | Yes | Yes | Yes | scheduled mining and reuse in loop |
| Pattern mining | Yes | Yes | Yes | RCA v2 and automatic fix routing |
| Continuous evaluation | Yes | Yes | Yes | persistent jobs and auto-remediation |
| Closed-loop self-learning | Partially | No | Yes | full orchestration |

Interpretation:
- Logos ADK already has strong self-improving primitives.
- The main gap is not data capture or evaluation anymore.
- The main gap is orchestration and policy automation.

## Closed Loop Architecture

```mermaid
flowchart LR
    A[Runtime Run] --> B[Run Capture]
    B --> C[Feedback / Outcomes]
    C --> D[Online Sync]
    D --> D1[Memory Sync]
    D --> D2[Retrieval Sync]
    D --> D3[Model Routing Sync]
    D --> D4[Tool / Workflow Sync]
    C --> E[Learning Store]
    E --> F[Dataset Builder]
    F --> G[Pattern Mining / Reflection]
    F --> H[Reward Scoring]
    F --> I[Evaluation Loop]
    G --> J[Prompt Candidate Generation]
    H --> K[Policy / Ranking]
    I --> K
    J --> L[Prompt Optimizer]
    K --> L
    L --> M[Prompt Registry / Experiments]
    M --> N[Deploy / Promote / Rollback]
    N --> A
```

Current state:
- `A -> E` exists
- `C -> D1` exists through `FeedbackAPI`
- `E -> F -> G/H/I` exists
- `L -> M` exists
- `N -> A` exists only as explicit operator action

Missing state:
- `D` is not centralized
- `G -> J -> L -> M -> N` is not automated as one loop
- `N` does not yet auto-rollback on sustained regression

## KPI Baseline

The baseline KPI set for self-learning changes is:

### Quality
- Source:
  - human feedback
  - judge results
  - regression pass rate
- Current sources in repo:
- `learning/evaluation/runner.py`
  - `quality_history.py`
  - `learning/improvement/reward_scorer.py`

### Reward
- Source:
  - human feedback
  - business outcomes
  - cost penalty
  - latency penalty
  - safety penalty
- Current implementation:
  - `RewardModel`

### Latency
- Source:
  - run metadata `latency_ms`
  - model routing event latencies
- Current use:
  - reward penalties
  - scorecards
  - routing and prompt guard logic

### Cost
- Source:
  - token usage
  - `DEFAULT_RATES`
  - estimated cost on runs/candidates
- Current use:
  - reward penalties
  - routing leaderboard
  - prompt guard

### Safety
- Source:
  - failure taxonomy, especially `policy_violation`
  - guardrail failures and operator feedback
- Current use:
  - reward penalties
  - prompt promotion guard

### Retrieval Relevance
- Source:
  - retrieval quality sync
  - source usefulness
  - bad context detection
- Current use:
  - retrieval profiles
  - source scores
  - scorecard deltas

### Tool Success
- Source:
  - tool call success/failure and duration
  - workflow branch/approval/loop stats
- Current use:
  - tool/workflow learning scores
  - scorecard deltas

## Baseline KPI Contract

Before implementing automatic orchestration, every intervention should be measured against:

- minimum sample size
- quality delta
- reward delta
- latency delta
- cost delta
- safety regression rate
- retrieval relevance delta
- tool success delta

Recommended minimum baseline report for any future self-learning run:

```yaml
baseline:
  sample_size: 0
  quality:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  reward:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  latency_ms:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  cost_usd:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  safety_violation_rate:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  retrieval_relevance:
    current: 0.0
    candidate: 0.0
    delta: 0.0
  tool_success:
    current: 0.0
    candidate: 0.0
    delta: 0.0
```

## Phase 0 Exit Criteria

Phase 0 is complete when:
- current learning modules are described by responsibility and status
- the implemented/runtime/manual/missing split is explicit
- the closed-loop architecture is documented
- baseline KPIs are fixed for future automation work
