High-Level Architecture
┌─────────────────────────────────────────────────────────────────────┐
│ AGENTIC ANALYST'S COCKPIT │
└─────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────┐
│ USER INTERFACE │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Command Input: [analyze my best session ] [Run] │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────┐ ┌────────────────────────────────────┐ │
│ │ BLUEPRINT PANEL │ │ EXECUTION TRACE │ │
│ │ │ │ │ │
│ │ Step 1: find_best │ │ [19:26:03] Parsing query... │ │
│ │ Step 2: get_summary │ │ [19:26:05] find_best_session() │ │
│ │ Step 3: detect_swings │ │ [19:26:05] Found: bab_20230512 │ │
│ │ Step 4: visualize │ │ [19:26:06] get_session_summary() │ │
│ │ │ │ [19:26:07] Detected 150 swings │ │
│ │ [Approve] [Cancel] │ │ [19:26:09] Completed in 4.23s │ │
│ └──────────────────────┘ └────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ AGENTIC ENGINE │
│ State: IDLE → PLANNING → AWAITING_APPROVAL → RUNNING → COMPLETED │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ PlanBuilder │ │ ToolRegistry │ │ ExecutionContext │ │
│ │ │ │ │ │ │ │
│ │ • Pattern match │ │ • 100+ tools │ │ • Session cache │ │
│ │ • Entity extract │ │ • Typed params │ │ • Step results │ │
│ │ • Build plan │ │ • Execute fn │ │ • Dependency │ │
│ │ │ │ │ │ resolution │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ DATA LAYER (TennisDataClient) │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │
│ │ tennis_watch.db │ │ ztennis.db │ │ BabPopExt.db │ │
│ │ (Apple Watch) │ │ (Zepp Universal) │ │ (Babolat PIQ) │ │
│ │ │ │ │ │ │ │
│ │ • sessions │ │ • swings │ │ • tb_activities │ │
│ │ • raw_sensor_buf │ │ • origins │ │ • tb_shots │ │
│ │ (100Hz IMU) │ │ (333Hz data) │ │ • piq_scores │ │
│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
State Machine
┌──────┐ parse_query() ┌──────────┐
│ IDLE ├─────────────────→│ PLANNING │
└──────┘ └────┬─────┘
│ Plan generated
▼
┌────────────────────────┐
│ AWAITING_APPROVAL │
└────┬──────────────┬────┘
approve() │ │ cancel()
▼ ▼
┌──────────┐ ┌──────────┐
│ RUNNING │ │ CANCELLED│
└────┬─────┘ └──────────┘
│ success / error
▼
┌───────────┐ ┌────────┐
│ COMPLETED │ │ FAILED │
└───────────┘ └────────┘
Component Responsibilities
| Component |
Location |
Responsibility |
| AgenticEngine |
agentic_engine.py |
State machine, plan execution, event callbacks |
| PlanBuilder |
plan_builder.py |
NL parsing, pattern matching, plan generation |
| ToolRegistry |
tool_registry.py |
Tool registration, parameter validation, execution |
| ExecutionContext |
execution_context.py |
Caching, step results, dependency resolution |
| TennisDataClient |
data_client.py |
SQLite queries, sensor data retrieval |
Execution Flow
| Step |
Action |
Output |
| 1 |
User enters query: "analyze my best session" |
Raw query string |
| 2 |
PlanBuilder.build_plan() - pattern matching |
ExecutionPlan with 4 steps |
| 3 |
UI displays Blueprint Panel for approval |
User clicks "Approve" |
| 4 |
AgenticEngine.execute_plan() - iterate steps |
Tool calls with resolved params |
| 5 |
ToolRegistry executes each tool |
Results cached in ExecutionContext |
| 6 |
Final step produces visualization |
Chart saved to /tmp/tennis_viz |
Caching Strategy
| Cache Type |
Key |
Value |
| Session Cache |
session_id |
Session summary dict |
| Sensor Data Cache |
session_id |
DataFrame with sensor readings |
| Step Results |
step_{id}_result |
Tool execution result |
| Query Cache |
query_hash |
Previous execution result |
Implementation Details
Full source code in cockpit_poc/agent/. Run tests with python -m pytest tests/. Interactive mode: python test_agent.py.