🛡️ 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:

1. Naive Truncation: Drops crucial initial instructions, setup parameters, or system constraints.
2. Raw RAG Dumping: Loses temporal ordering, state mutations, and causal dependencies.
3. 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

📐 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.