Spaces:
Build error
Build error
File size: 3,874 Bytes
61e7398 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 | # SharedContext — Compressed Inter-Agent Context Sharing
When agents hand off to each other, context gets replayed in full. SharedContext compresses what moves between agents using Headroom's compression pipeline.
## Quick Start
```python
from headroom import SharedContext
ctx = SharedContext()
# Agent A stores large output
ctx.put("research", big_research_output, agent="researcher")
# Agent B gets compressed version (~80% smaller)
summary = ctx.get("research")
# Agent B needs full details
full = ctx.get("research", full=True)
```
## API
### `put(key, content, *, agent=None)`
Store content under a key. Compresses automatically using Headroom's full pipeline (SmartCrusher for JSON, CodeCompressor for code, Kompress for text).
```python
entry = ctx.put("findings", big_json_output, agent="researcher")
entry.original_tokens # 20,000
entry.compressed_tokens # 4,000
entry.savings_percent # 80.0
entry.transforms # ["router:json:0.20"]
```
### `get(key, *, full=False)`
Retrieve content. Returns compressed version by default, original with `full=True`.
```python
compressed = ctx.get("findings") # 4K tokens
original = ctx.get("findings", full=True) # 20K tokens
missing = ctx.get("nonexistent") # None
```
### `get_entry(key)`
Get the full `ContextEntry` with metadata.
```python
entry = ctx.get_entry("findings")
entry.key # "findings"
entry.agent # "researcher"
entry.original_tokens # 20000
entry.compressed_tokens # 4000
entry.savings_percent # 80.0
entry.timestamp # 1710000000.0
entry.transforms # ["router:json:0.20"]
```
### `keys()`
List all non-expired keys.
### `stats()`
Aggregated stats across all entries.
```python
stats = ctx.stats()
stats.entries # 3
stats.total_original_tokens # 60000
stats.total_compressed_tokens # 12000
stats.total_tokens_saved # 48000
stats.savings_percent # 80.0
```
### `clear()`
Remove all entries.
## Configuration
```python
ctx = SharedContext(
model="claude-sonnet-4-5-20250929", # For token counting
ttl=3600, # 1 hour (default)
max_entries=100, # Evicts oldest when full
)
```
## Framework Examples
### CrewAI
```python
from headroom import SharedContext
ctx = SharedContext()
# After researcher task
ctx.put("findings", researcher_task.output.raw)
# Coder task gets compressed context
coder_context = ctx.get("findings")
```
### LangGraph
```python
from headroom import SharedContext
ctx = SharedContext()
def researcher_node(state):
result = do_research()
ctx.put("research", result)
return {"research_summary": ctx.get("research")}
def coder_node(state):
# Compressed summary in state, full details on demand
full = ctx.get("research", full=True)
return {"code": write_code(full)}
```
### OpenAI Agents SDK
```python
from headroom import SharedContext
ctx = SharedContext()
def compress_handoff(messages):
for msg in messages:
if len(msg.content) > 1000:
ctx.put(msg.id, msg.content)
msg.content = ctx.get(msg.id)
return messages
handoff(agent=coder, input_filter=compress_handoff)
```
### Any Framework
SharedContext is framework-agnostic. It's just `put()` and `get()`. Use it wherever context moves between agents.
## How It Works
Under the hood, `put()` calls `headroom.compress()` (the same pipeline used by the proxy) and stores the original in memory. `get()` returns the compressed version. `get(full=True)` returns the original.
- JSON arrays → SmartCrusher (70-95% compression)
- Code → CodeCompressor (AST-aware, with `[code]` extra)
- Text → Kompress (ModernBERT, with `[ml]` extra) or passthrough
- Entries expire after TTL (default 1 hour)
- Oldest entries evicted when max_entries reached
|