Metadata-Version: 2.4
Name: aurarouter-antigravity
Version: 0.1.0
Summary: Google Antigravity MCP provider server for AuraRouter — orchestrates agentic workflows and Gemini models via the google-antigravity SDK.
Author: AuraCore Dynamics Inc.
License: Apache-2.0
Keywords: aurarouter,antigravity,gemini,agent,mcp,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: google-antigravity>=0.1.20
Requires-Dist: mcp[cli]
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Dynamic: license-file

# aurarouter-antigravity

Google Antigravity MCP provider server for [AuraRouter](https://github.com/AuraCoreDynamics/aurarouter).

`aurarouter-antigravity` wraps the official [`google-antigravity`](https://github.com/google-antigravity/antigravity-sdk-python) Python SDK, exposing Google Antigravity agentic capabilities and Gemini models as a standard Model Context Protocol (MCP) server.

---

## Architecture Overview

```mermaid
graph TD
    Client[User / Application / MAS] --> Router[AuraRouter ComputeFabric]
    Router --> Stack{v2.1 Routing Stack}
    Stack -->|Select Antigravity| MCP[AuraRouter McpProvider]
    MCP --> FastMCP[aurarouter-antigravity FastMCP Server]
    FastMCP --> Provider[AntigravityProvider Engine]
    Provider --> SDK[google-antigravity SDK: Agent / LocalAgentConfig]
    SDK --> Gateway[Google Gemini / Vertex AI Endpoint]
```

---

## Features

- **Native `google-antigravity` SDK Integration**: Directly utilizes `google.antigravity.Agent` and `LocalAgentConfig` with streaming response resolution.
- **Model Catalog**:
  - `gemini-3.8-flash`: Default Antigravity model for high-efficiency reasoning and agent workflows.
  - `gemini-3.1-pro`: Deep reasoning and long-context (2M tokens) agent execution.
  - `gemini-3.5-flash`: Balanced latency and multimodal reasoning.
  - `gemini-2.5-pro` & `gemini-2.5-flash`: Proven production generation.
- **AuraRouter v2.1 Telemetry & Error Isolation**:
  - Maps `RESOURCE_EXHAUSTED` / `QuotaFailure` to `AntigravityRateLimitError` (`rate_limit_exceeded`) with `retry_after_s`.
  - Maps context overflow to `AntigravityContextLengthError` (`context_length_exceeded`).
  - Maps 5xx / connection timeouts to `AntigravityTransientError` (`provider_transient_error`).
- **Structured Outputs**: Native support for JSON schemas and `json_mode`.
- **Accurate Telemetry**: Tracks prompt tokens, completion tokens, and Time-to-First-Token (TTFT) via monotonic clocks.

---

## Installation

```bash
pip install aurarouter-antigravity
```

To install from source:

```bash
cd C:\projects\auracore\aurarouter-antigravity
pip install -e .
```

---

## Environment Configuration

| Variable | Description |
|---|---|
| `GEMINI_API_KEY` | Google Gemini API key (recommended) |
| `GOOGLE_API_KEY` | Fallback Google API key variable |
| `ANTIGRAVITY_APP_DATA_DIR` | Path to Antigravity app data directory (default: `~/.gemini/antigravity`) |
| `GOOGLE_GENAI_USE_VERTEXAI` | Set to `"true"` to route via Google Cloud Vertex AI |
| `GOOGLE_CLOUD_PROJECT` | GCP Project ID when using Vertex AI |
| `GOOGLE_CLOUD_LOCATION` | GCP Region when using Vertex AI (e.g. `us-central1`) |

---

## AuraRouter Integration

In your AuraRouter configuration file (`auraconfig.yaml`), add Antigravity models:

```yaml
models:
  gemini-3.8-flash:
    provider: mcp
    provider_name: antigravity
    hosting_tier: cloud
    cost_per_1m_input: 0.15
    cost_per_1m_output: 0.60
    context_limit: 1048576
    capabilities: [code, reasoning, agent, chat, multimodal]

  gemini-3.1-pro:
    provider: mcp
    provider_name: antigravity
    hosting_tier: cloud
    cost_per_1m_input: 1.25
    cost_per_1m_output: 10.00
    context_limit: 2097152
    capabilities: [code, reasoning, agent, chat, complex]

roles:
  lead_architect:
    - gemini-3.1-pro
    - claude-3-5-sonnet-20241022
  fast_coder:
    - gemini-3.8-flash
    - gpt-4o-mini
```

When installed in the Python environment, AuraRouter automatically discovers `antigravity` via the `aurarouter.providers` entry point.

---

## Direct Python Usage

```python
from aurarouter_antigravity.provider import AntigravityProvider

provider = AntigravityProvider()

# Single-shot text generation
result = provider.generate(
    prompt="Explain quantum annealing in simple terms.",
    model="gemini-3.8-flash"
)
print(f"Response: {result['text']}")
print(f"Tokens: {result['input_tokens']} in / {result['output_tokens']} out (TTFT: {result['ttft_s']:.3f}s)")

# Multi-turn conversation
history_result = provider.generate_with_history(
    messages=[
        {"role": "user", "content": "Hello!"},
        {"role": "assistant", "content": "Greetings! How may I assist you?"},
        {"role": "user", "content": "What is the capital of France?"}
    ],
    system_prompt="Be concise and factual.",
    model="gemini-3.8-flash"
)
print(history_result["text"])
```

---

## MCP Tools Exposed

| Tool Name | Description |
|---|---|
| `provider.generate` | Single-shot text generation via Antigravity Agent |
| `provider.generate_with_history` | Multi-turn conversation execution with dialogue context |
| `provider.list_models` | List available Antigravity models and specifications |
| `provider.capabilities` | Advertise provider features (streaming, structured output, subagents) |
| `provider.health_check` | Readiness check for the Antigravity provider |

---

## Running Standalone

Start the FastMCP server over standard I/O:

```bash
python -m aurarouter_antigravity
```

Display CLI options and help:

```bash
python -m aurarouter_antigravity --help
```

---

## Testing & Verification

Run the full test suite:

```bash
pytest C:\projects\auracore\aurarouter-antigravity\tests -v
```

Run live vendor canary verification (requires `GEMINI_API_KEY`):

```bash
pytest C:\projects\auracore\aurarouter-antigravity\tests\test_live_vendor.py -v -m live_vendor
```

---

## License

Apache-2.0
