Skip to main content

Antigravity Context Shield Banner

🛡️ Antigravity Context Shield (antigravity-context-shield)

Python 3.11+ License: MIT CI Coverage Code Style: Black

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

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)

Source distribution for antigravity-context-shield 0.1.0
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)

Table of built distributions (wheels) for antigravity-context-shield 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page