feat: Implement ACE Context Engineering framework (SYS_17)

Complete implementation of Agentic Context Engineering (ACE) framework:

Core modules (optimization_engine/context/):
- playbook.py: AtomizerPlaybook with helpful/harmful scoring
- reflector.py: AtomizerReflector for insight extraction
- session_state.py: Context isolation (exposed/isolated state)
- feedback_loop.py: Automated learning from trial results
- compaction.py: Long-session context management
- cache_monitor.py: KV-cache optimization tracking
- runner_integration.py: OptimizationRunner integration

Dashboard integration:
- context.py: 12 REST API endpoints for playbook management

Tests:
- test_context_engineering.py: 44 unit tests
- test_context_integration.py: 16 integration tests

Documentation:
- CONTEXT_ENGINEERING_REPORT.md: Comprehensive implementation report
- CONTEXT_ENGINEERING_API.md: Complete API reference
- SYS_17_CONTEXT_ENGINEERING.md: System protocol
- Updated cheatsheet with SYS_17 quick reference
- Enhanced bootstrap (00_BOOTSTRAP_V2.md)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
2025-12-29 20:21:20 -05:00
parent 0110d80401
commit 773f8ff8af
19 changed files with 8184 additions and 2 deletions

View File

@@ -34,6 +34,7 @@ requires_skills:
| Add custom physics extractor | EXT_01 | Create in `optimization_engine/extractors/` |
| Add lifecycle hook | EXT_02 | Create in `optimization_engine/plugins/` |
| Generate physics insight | SYS_16 | `python -m optimization_engine.insights generate <study>` |
| **Manage knowledge/playbook** | **SYS_17** | `from optimization_engine.context import AtomizerPlaybook` |
---
@@ -366,6 +367,7 @@ Without it, `UpdateFemodel()` runs but the mesh doesn't change!
| 14 | Neural | Surrogate model acceleration |
| 15 | Method Selector | Recommends optimization strategy |
| 16 | Study Insights | Physics visualizations (Zernike, stress, modal) |
| 17 | Context Engineering | ACE framework - self-improving knowledge system |
---
@@ -549,3 +551,106 @@ convert_custom_to_optuna(db_path, study_name)
- Trial numbers **NEVER reset** across study lifetime
- Surrogate predictions (5K per batch) are NOT logged as trials
- Only FEA-validated results become trials
---
## Context Engineering Quick Reference (SYS_17)
The ACE (Agentic Context Engineering) framework enables self-improving optimization through structured knowledge capture.
### Core Components
| Component | Purpose | Key Function |
|-----------|---------|--------------|
| **AtomizerPlaybook** | Structured knowledge store | `playbook.add_insight()`, `playbook.get_context_for_task()` |
| **AtomizerReflector** | Extracts insights from outcomes | `reflector.analyze_outcome()` |
| **AtomizerSessionState** | Context isolation (exposed/isolated) | `session.get_llm_context()` |
| **FeedbackLoop** | Automated learning | `feedback.process_trial_result()` |
| **CompactionManager** | Long-session handling | `compactor.maybe_compact()` |
| **CacheMonitor** | KV-cache optimization | `optimizer.track_completion()` |
### Python API Quick Reference
```python
from optimization_engine.context import (
AtomizerPlaybook, AtomizerReflector, get_session,
InsightCategory, TaskType, FeedbackLoop
)
# Load playbook
playbook = AtomizerPlaybook.load(Path("knowledge_base/playbook.json"))
# Add an insight
playbook.add_insight(
category=InsightCategory.STRATEGY, # str, mis, tool, cal, dom, wf
content="CMA-ES converges faster on smooth mirror surfaces",
tags=["mirror", "sampler", "convergence"]
)
playbook.save(Path("knowledge_base/playbook.json"))
# Get context for LLM
context = playbook.get_context_for_task(
task_type="optimization",
max_items=15,
min_confidence=0.5
)
# Record feedback
playbook.record_outcome(item_id="str_001", helpful=True)
# Session state
session = get_session()
session.exposed.task_type = TaskType.RUN_OPTIMIZATION
session.add_action("Started optimization run")
llm_context = session.get_llm_context()
# Feedback loop (automated learning)
feedback = FeedbackLoop(playbook_path)
feedback.process_trial_result(
trial_number=42,
params={'thickness': 10.5},
objectives={'mass': 5.2},
is_feasible=True
)
```
### Insight Categories
| Category | Code | Use For |
|----------|------|---------|
| Strategy | `str` | Optimization approaches that work |
| Mistake | `mis` | Common errors to avoid |
| Tool | `tool` | Tool usage patterns |
| Calculation | `cal` | Formulas and calculations |
| Domain | `dom` | FEA/NX domain knowledge |
| Workflow | `wf` | Process patterns |
### Playbook Item Format
```
[str_001] helpful=5 harmful=0 :: CMA-ES converges faster on smooth surfaces
```
- `net_score = helpful - harmful`
- `confidence = helpful / (helpful + harmful)`
- Items with `net_score < -3` are pruned
### REST API Endpoints
| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/api/context/playbook` | GET | Playbook summary stats |
| `/api/context/playbook/items` | GET | List items with filters |
| `/api/context/playbook/feedback` | POST | Record helpful/harmful |
| `/api/context/playbook/insights` | POST | Add new insight |
| `/api/context/playbook/prune` | POST | Remove harmful items |
| `/api/context/session` | GET | Current session state |
| `/api/context/learning/report` | GET | Comprehensive learning report |
### Dashboard URL
| Service | URL | Purpose |
|---------|-----|---------|
| Context API | `http://localhost:5000/api/context` | Playbook management |
**Full documentation**: `docs/protocols/system/SYS_17_CONTEXT_ENGINEERING.md`