How ammar-abagumbul/tokencake works
TokenCake is an agent-aware KV-cache scheduler for multi-agent LLM serving. In the documented current milestone, an agent workflow follows a dependency DAG, calls an LLM and external tools, and brackets tool stalls with frontend events. The frontend delegates those events to the temporal controller, which forecasts stall duration, gates offload decisions, and plans cache uploads; the connector integrates KV migration with vLLM. The README also describes a spatial scheduler, but the stated milestone targets temporal scheduling and no spatial implementation path appears in the tree. Unsampled policy wiring is shown only where documented.
Main entry points: workflow.py Workflow driver · controller.py Temporal controller · api.py Event API · connector.py vLLM KV connector
Components 13
Agent workload
- Agent applications
agents/apps.py - Agent DAG
src/tokencake/graph.py - Workflow driver
agents/workflow.py - Tool execution
agents/tools.py
Frontend control
- Event API
src/tokencake/frontend/api.py
Temporal policy
- Temporal controller
src/tokencake/temporal/controller.py - Duration forecast
src/tokencake/temporal/forecast.py - Offload gate
src/tokencake/temporal/gate.py - Upload planner
src/tokencake/temporal/prefetch.py
KV serving
- CPU block manager
src/tokencake/offload_manager.py - vLLM KV connector
src/tokencake/connector.py
Other components
- Application caller
- vLLM server
Connections 13
- Application caller → Workflow driver: starts workflow
- Agent applications → Agent DAG: builds DAG
- Workflow driver → Agent DAG: executes DAG
- Workflow driver → vLLM server: requests inference
- Workflow driver → Tool execution: executes tools
- Workflow driver → Event API: posts events
- Event API → Temporal controller: dispatches events
- Temporal controller → Duration forecast: predicts duration
- Temporal controller → Offload gate: requests decision
- Temporal controller → CPU block manager: manages cache
- Temporal controller → Upload planner: plans uploads
- vLLM server → vLLM KV connector: invokes connector
- vLLM KV connector → CPU block manager: tracks KV blocks