# Self-Learning Roadmap

This roadmap translates the self-learning plan into implementation phases with checklists.

Current framing:
- Logos ADK is not "learning infrastructure only"
- the platform already has strong self-improving primitives
- the main gap is orchestration and policy automation

The priority order is:
1. `LearningCoordinator`
2. `SelfLearningLoop`
3. `PromptCandidateGenerator`
4. learned reward scoring
5. persistent continuous evaluation and rollback policies
6. RCA v2 / cross-agent / meta-learning

## Phase 0. Stabilize Baseline

Result:
- the current capability surface is fixed and documented before orchestration changes begin

Checklist:
- [x] Describe current capabilities by module:
  - `logos_adk/learning/improvement/`
  - `logos_adk/learning/evaluation/`
  - `logos_adk/learning/optimizer.py`
  - `logos_adk/learning/feedback_api.py`
- [x] Split documentation into `implemented`, `runtime-connected`, `manual-only`, `missing`
- [x] Add a closed-loop architecture diagram:
  - `feedback -> sync -> analyze -> generate -> eval -> deploy -> monitor`
- [x] Fix baseline KPIs:
  - quality
  - reward
  - latency
  - cost
  - safety
  - retrieval relevance
  - tool success

Artifacts:
- [x] [`docs/self-learning-baseline.md`](self-learning-baseline.md)

## Phase 1. Centralize Online Learning

Result:
- online updates are no longer tied to HTTP routes and can run from any entrypoint

Checklist:
- [ ] Create `logos_adk/learning/coordinator.py`
- [ ] Move retrieval/model-routing sync out of `logos_adk/serve_routes.py`
- [ ] Attach coordinator to `FeedbackAPI`
- [ ] Add sync subscribers:
  - [ ] memory sync
  - [ ] retrieval sync
  - [ ] model-routing sync
  - [ ] workflow sync placeholder
- [ ] Add idempotency by `trace_id`
- [ ] Add integration tests:
  - [ ] feedback through API
  - [ ] feedback outside HTTP path
  - [ ] outcome-only path

## Phase 2. Build Self-Learning Loop

Result:
- an automated closed loop exists above current engines

Checklist:
- [ ] Create `logos_adk/learning/loop.py`
- [ ] Implement `SelfLearningLoop.run_once()`
- [ ] Implement `collect_failures()`
- [ ] Implement `mine_patterns()`
- [ ] Implement `generate_candidates()`
- [ ] Implement `evaluate_candidates()`
- [ ] Implement `deploy_or_experiment()`
- [ ] Add policy thresholds:
  - [ ] minimum sample size
  - [ ] minimum lift
  - [ ] no safety regression
  - [ ] max latency regression
  - [ ] max cost regression
- [ ] Add `dry_run`
- [ ] Add audit trail for rejected/promoted candidates

## Phase 3. Add Automatic Prompt Evolution

Result:
- prompt optimization stops being manual-only

Checklist:
- [ ] Create `logos_adk/learning/prompt_evolution.py`
- [ ] Add `PromptCandidateGenerator.generate()`
- [ ] Support generation strategies:
  - [ ] patch
  - [ ] rewrite
  - [ ] compress
  - [ ] style correction
  - [ ] retrieval grounding
- [ ] Connect generator to `SelfLearningLoop`
- [ ] Reuse `PromptOptimizer` for ranking
- [ ] Save candidate provenance into `PromptRegistry` metadata
- [ ] Add offline benchmark tests on synthetic and prod-derived golden cases

## Phase 4. Upgrade Reward Modeling

Result:
- reward can run in heuristic and learned modes

Checklist:
- [ ] Introduce `RewardScorer` interface
- [ ] Rename/adapt current `RewardModel` into heuristic scorer role
- [ ] Add `LearnedPreferenceScorer` in `logos_adk/learning/reward.py`
- [ ] Build pairwise preference datasets from:
  - [ ] `edited_answer`
  - [ ] `expected_output`
  - [ ] suggestion accepted/rejected
- [ ] Implement train/export/load lifecycle
- [ ] Use learned scorer in candidate ranking and champion/challenger
- [ ] Compare heuristic vs learned scorer on holdout data

## Phase 5. Harden Continuous Evaluation

Result:
- continuous eval becomes production-grade

Checklist:
- [x] Persist continuous eval job definitions
- [x] Restore jobs on app startup in `logos_adk/serve.py`
- [x] Add degrade thresholds and alerts
- [x] Auto-disable experiments on safety/quality regression
- [x] Auto-rollback prompt deployment on confirmed degradation
- [x] Generate trend-delta and incident reports
- [x] Add restart recovery and rollback tests

## Phase 6. Improve RCA

Result:
- failure analysis moves closer to real root-cause analysis

Checklist:
- [x] Create `RootCauseAnalyzer`
- [x] Add automatic classification when `failure_types` are missing
- [x] Add correlations across:
  - [x] prompt version
  - [x] model
  - [x] tool path
  - [x] retrieval profile
  - [x] workspace/task segment
- [x] Add ranked hypotheses with confidence
- [x] Add suggested fix and affected surface
- [x] Export RCA reports through API and CLI

## Phase 7. Cross-Agent Learning

Result:
- improvements can transfer beyond one agent

Checklist:
- [x] Create `KnowledgeTransferEngine`
- [x] Define transferable artifacts:
  - [x] reflection lessons
  - [x] prompt patches
  - [x] retrieval profiles
  - [x] tool preferences
  - [x] routing policies
- [x] Separate agent-local and shared scopes
- [x] Add compatibility rules:
  - [x] task type
  - [x] workspace
  - [x] guardrails
- [x] Add safe-apply recommendation-first mode
- [x] Measure transfer uplift separately from local uplift

## Phase 8. Meta-Learning

Result:
- the system learns which intervention is best

Checklist:
- [x] Log every intervention:
  - [x] prompt patch
  - [x] routing change
  - [x] retrieval change
  - [x] tool policy change
- [x] Measure uplift by intervention type
- [x] Prefer cheapest successful intervention first
- [x] Add decision rules:
  - [x] when to patch
  - [x] when to experiment
  - [x] when to rollback
  - [x] when to require human review
- [x] Build ROI leaderboard for learning strategies

## Definition Of Done

- [ ] Closed loop can go from negative feedback to candidate deployment without manual multi-step API choreography
- [ ] Online updates work outside the web routes
- [ ] Continuous eval jobs survive restart
- [ ] Regression automatically blocks or rolls back bad promotion
- [ ] Reward scoring supports heuristic and learned modes
- [ ] RCA returns hypothesis, confidence, and suggested fix
- [ ] End-to-end tests exist for the full self-learning path
