🛡️ Antigravity Context Shield (antigravity-context-shield)
Dynamic Context Compactor & Semantic State Graph for Long-Running Autonomous AI Agents.
antigravity-context-shield is an open-source, production-ready Python library engineered to eliminate Context Degradation ("Context Rot"), Silent Context Drift, and Hallucination Accumulation in long-running agent loops (e.g. software engineering agents, browser automation, long task loops).
🎯 The Problem
As autonomous agent loops execute over hours or days, context windows fill up with raw tool outputs (e.g., thousands of lines of terminal stdout, large file reads) and stale reasoning paths. Standard implementations suffer from:
- Naive Truncation: Drops crucial initial instructions, setup parameters, or system constraints.
- Raw RAG Dumping: Loses temporal ordering, state mutations, and causal dependencies.
- Infinite Error Loops: Agents repeatedly attempt failing tool commands with identical parameters without realizing system state hasn't changed.
🚀 Key Features
- ⚡ Active Context Pruning Engine: Automatically compresses long terminal outputs and raw file reads while preserving stack traces and structural signatures. Collapses duplicate/polling action sequences into high-level notices.
- 🕸️ Semantic State Graph (SSG): Models multi-turn execution as a Directed Acyclic Graph (DAG) of Turns, Tools, and State updates. Extracts the minimal active causal execution path, discarding failed/abandoned attempts.
- 🛡️ Anti-Hallucination Guardrails: Pre-turn middleware that cross-references proposed prompt claims against active state nodes to detect state drift and block action redundancy.
- 🔌 Framework Agnostic & SDK Adapters: Native hooks for Google Antigravity SDK (
google-antigravity), LangChain, and LlamaIndex.
📊 Benchmarks
| Metric | Without Shield | With antigravity-context-shield |
Improvement |
|---|---|---|---|
| 5-Turn Agent History | 8,605 chars (~2,150 tokens) | 1,383 chars (~345 tokens) | 83.93% Reduction |
| Redundant Tool Loop Deflection | 0% (Loops indefinitely) | 100% (Pre-emptively blocked) | Zero Hallucination Loops |
| Test Coverage | N/A | 90% Unit Test Coverage | Production Ready |
📐 Architecture
flowchart LR
subgraph Execution Loop
User[User Goal] --> Agent[Autonomous Agent]
Agent --> Shield[Context Shield Middleware]
Shield --> Guard[Anti-Hallucination Guardrails]
Guard --> Model[LLM / Gemini Dispatch]
end
subgraph Memory Architecture
Model --> Tools[Tool Executions]
Tools --> Pruner[Active Context Pruner]
Tools --> SSG[Semantic State Graph DAG]
Pruner --> ActiveContext[Compacted Active History]
SSG --> ActiveContext
ActiveContext --> Agent
end
🛠️ Quickstart
Installation
pip install antigravity-context-shield
1. Integrating with Google Antigravity SDK
from google.antigravity import LocalAgentConfig
from antigravity_context_shield import ContextShieldAntigravityAdapter, ContextShieldConfig
# Instantiate Shield Config & Adapter
shield_config = ContextShieldConfig(
max_message_length=1000,
enable_terminal_pruning=True,
enable_file_read_pruning=True,
enable_duplicate_run_pruning=True,
enable_guardrails=True
)
shield_adapter = ContextShieldAntigravityAdapter(config=shield_config)
# Register hooks with LocalAgentConfig
agent_config = LocalAgentConfig(
hooks=shield_adapter.get_registered_hooks()
)
2. Standalone Compaction Engine
from antigravity_context_shield import ContextCompactorEngine, Message, MessageRole, ToolCall
engine = ContextCompactorEngine()
messages = [
Message(role=MessageRole.USER, content="Run build tests."),
Message(
role=MessageRole.ASSISTANT,
content="Running pytest...",
tool_calls=[ToolCall(id="tc1", name="bash", arguments={"cmd": "pytest"}, output="VERY LONG STDOUT LOG...")]
)
]
compacted_messages = engine.compact_messages(messages)
3. LangChain & LlamaIndex Callback Handlers
from antigravity_context_shield import ContextShieldLangChainCallbackHandler
handler = ContextShieldLangChainCallbackHandler()
# Pass `handler` into LangChain agent callbacks: agent.run(..., callbacks=[handler])
🧪 Running Examples & Tests
Run Unit Tests
pytest -v --cov=src/antigravity_context_shield tests/
Run Benchmark Demonstration Scripts
# Baseline without shield (watch context size grow)
python3 examples/run_without_shield.py
# With Shield enabled (watch >80% token reduction)
python3 examples/run_with_shield.py
📄 License
Distributed under the MIT License. See LICENSE for details.
Metadata
Release files for antigravity-context-shield 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| antigravity_context_shield-0.1.0.tar.gz | 891.1 kB | Without provenance | Details for antigravity_context_shield-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| antigravity_context_shield-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for antigravity_context_shield-0.1.0-py3-none-any.whl |
Total release size: 913.4 kB
Release files / antigravity_context_shield-0.1.0.tar.gz
| Download URL | antigravity_context_shield-0.1.0.tar.gz |
|---|---|
| Size | 891.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
77dba6f1a98c52666c6be1f8432a57d308c601dd20546a1876883b542c5ac357
|
|
BLAKE2b-256 checksum How to use checksums |
e5c4865046b63e96a0afdecafc4c89ac16f1b4f87844246593ac46ac93a76c91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Release files / antigravity_context_shield-0.1.0-py3-none-any.whl
| Download URL | antigravity_context_shield-0.1.0-py3-none-any.whl |
|---|---|
| Size | 22.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
71252d533a7d475ecb13a27b542c79019606576f459541f7e36744b6ec7f0350
|
|
BLAKE2b-256 checksum How to use checksums |
1414330b09777c3d21b07457aeebfeae52ac5f57ad2efacfcb47b55c35145ada
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Security for antigravity-context-shield 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.