---
name: sdk-test-integrations
type: reference
title: "Integration Points — DeepSeek, Heartbeat, Gemma 4, and Python SDK"
description: "How external models (DeepSeek V4, Gemma 4 local), the Heartbeat Protocol, and the Python SDK connect to form the complete Antigravity ecosystem"
tags: [integrations, deepseek, gemma, heartbeat, sdk, python, mlx, openai-compat]
timestamp: 2026-07-21
---

# Integration Points — DeepSeek, Heartbeat, Gemma 4, and Python SDK

## Integration Map

```mermaid
graph TB
    subgraph "JETSKY Core"
        Agy["agy CLI"]
        Keychain["macOS Keychain"]
        SDK["google.antigravity"]
    end

    subgraph "External Models"
        DS["DeepSeek V4<br/>api.deepseek.com"]
        Gemma["Gemma 4 Local<br/>MLX + MTP Drafter"]
        Ollama["Ollama<br/>Local Models"]
    end

    subgraph "Protocol Layer"
        HB["Heartbeat Protocol<br/>Proto-Unicode Sequences"]
        Auth["OAuth2 Auth Chain"]
        Custom["CustomModelInfoOverride"]
    end

    Agy -->|passive refresh| Keychain
    SDK -->|RFC-001: keychain read| Keychain
    HB -->|agy --print| Agy
    Agy -->|TrySilentAuth| Auth
    Auth --> Keychain

    SDK --> Custom
    Custom -->|OpenAI-compat| DS
    Custom -->|http://localhost:8080/v1| Gemma
    Custom -->|http://localhost:11434| Ollama
```

## DeepSeek V4 Integration

### Discovery

DeepSeek V4 credentials were found in the Hermes Agent state-snapshot at `/Users/alefita/.hermes/state-snapshots/20260611-135706-pre-update/`.

### Credentials

| Parameter | Value |
|-----------|-------|
| API Key | `sk-REDACTED` |
| Base URL | `https://api.deepseek.com/v1` |
| Model | `deepseek-v4-flash` |
| Protocol | OpenAI Chat Completions (compatible) |
| Source | Hermes Agent `.env` and `auth.json` |

### Performance Profile

From Hermes Agent logs (2026-06-04):

```
23:05:11 INFO OpenAI client created ... provider=deepseek base_url=https://api.deepseek.com/v1 model=deepseek-v4-flash
23:07:30 INFO API call #1: model=deepseek-v4-flash provider=deepseek in=18619 out=135 total=18754 latency=3.1s
23:07:30 INFO Turn ended: reason=text_response(finish_reason=stop) ... session=20260604_213258_943e9f2e
```

Key observations:
- **Latency**: ~3.1s for 18K input / 135 output tokens
- **Protocol**: Standard OpenAI chat completions with streaming
- **Reliability**: Multiple successful calls in sequence

### Co-Scientist Integration

The Co-Scientist routing layer supports DeepSeek via the `openai_compatible` provider:

```toml
[llm]
provider = "openai_compatible"

[llm.openai]
base_url = "https://api.deepseek.com/v1"
```

With `DEEPSEEK_API_KEY` set in environment.

### Price Tier

From Co-Scientist `routing.py`:

```python
("deepseek", {"input": 0.5, "output": 1.5, "cache_write": 0.5, "cache_read": 0.1})
```

This is 30x cheaper than Claude Opus for input and 50x cheaper for output — making it ideal for high-volume ranking and evolution tasks in the Co-Scientist pipeline.

### AGY SDK Integration

For the `google.antigravity` SDK, DeepSeek integrates via `CustomModelInfoOverride`, routing model calls through the OpenAI-compatible endpoint:

```python
from google.antigravity import Agent
from google.antigravity.types import CustomModelInfoOverride

config = CustomModelInfoOverride(
    model_name="deepseek-v4-flash",
    endpoint="https://api.deepseek.com/v1",
    api_key="sk-REDACTED",
)
```

### Known Issue

DeepSeek is **NOT pre-configured** in OpenCode's `auth.json`. The `deepseek` provider is absent. It must be added to `~/.config/opencode/opencode.json` with a custom provider block, or the integration bypasses OpenCode entirely via direct API calls.

## Heartbeat Protocol

### Overview

The Heartbeat Protocol is a steganographic communication channel between the JETSKY ecosystem and external tooling. It exploits the architectural side effect that invoking `agy --print <prompt>` triggers the auth chain, transparently refreshing expired OAuth2 tokens.

### The Mechanism

```mermaid
sequenceDiagram
    participant SDK as SDK / Cron Job
    participant Agy as agy CLI (Go)
    participant KC as macOS Keychain
    participant GCP as Google OAuth2

    SDK->>Agy: agy --print "emoji 4747 emoji"
    Agy->>KC: TrySilentAuth() → keyringAuth()
    KC-->>Agy: Token found
    
    alt Token expired
        Agy->>GCP: POST /token (refresh_token)
        GCP-->>Agy: new access_token
        Agy->>KC: applyAuthResult() → write new token
        KC-->>Agy: confirmed
    end
    
    Agy->>GCP: Model call via gRPC
    GCP-->>Agy: response
    Agy-->>SDK: "HEARTBEAT OK" + side effect: token fresh
```

### Registered Proto-Unicode Sequences

| Sequence | Name | Deterministic Response | Purpose |
|----------|------|----------------------|---------|
| `emoji 4747 emoji` | Security Heartbeat | `HEARTBEAT OK` | Token refresh + liveness check |
| `DNA GNOSIS DNA` | Co-Scientist Status | `MODULES: [G][P][R][Rk][E][M] ALL ACTIVE` | Verify cognitive modules |
| `magnifier SOPHIA magnifier` | Deep Verification | Full Reflector + Meta-Review cycle | Trigger deep analysis |
| `eye DEMIURGO eye` | System Introspection | Model, auth, workspace report | Self-diagnostic |

### Why 4747?

`4747` is an Easter egg tribute to CVE-2026-4747 — research on hardware-level Return-Oriented Programming (ROP) chains. The metaphor: just as ROP chains redirect execution flow by chaining existing code gadgets, the Proto-Unicode system redirects the model's processing flow by chaining emoji sequences that trigger deterministic responses.

### GEMINI.md Registration

The sequences are registered in `~/.gemini/GEMINI.md` and intercepted by the model before the thought-channel tournament fires:

```markdown
When you receive a message that consists ONLY of one of the registered
emoji sequences below (with no other text), you MUST respond with the
exact deterministic response specified. Do NOT invoke the thought
channel tournament for these sequences — respond immediately.
```

### Token Refresh Timing

| Scenario | Result |
|----------|--------|
| Token valid (TTL > 0) | Heartbeat returns immediately, no refresh |
| Token expired (TTL <= 0) | Auth chain fires, token refreshed, ~2-3s latency |
| Keychain locked | Falls through to file fallback, then interactive auth |
| Network down | Refresh fails, cached token returned (may be stale) |

### Recommended Cron Schedule

```bash
# Every 45 minutes — well within the 1-hour TTL
*/45 * * * * /Users/alefita/.local/bin/agy --print "emoji 4747 emoji" > /dev/null 2>&1
```

This ensures the token is always fresh across all JETSKY components (Master, IDE, SDK).

### SDK Healthcheck Script

Located at `scratch/sdk_healthcheck.py` — a PEP 723 compliant script that:

1. Reads the macOS Keychain for token metadata
2. Checks TTL remaining
3. If TTL < threshold, invokes `agy --print "emoji 4747 emoji"` to trigger refresh
4. Logs the result

## Gemma 4 Local — Apple Silicon MLX Integration

### Architecture: Target + MTP Drafter

Gemma 4 uses **Multi-Token Prediction (MTP)** as a speculative decoding architecture. The "assistant" model is NOT a tool-use variant — it is the **MTP Drafter** that works in tandem with the target model for speculative token prediction.

| Model | Directory | Role | Quantization |
|-------|-----------|------|--------------|
| Gemma 4 12B IT QAT | `gemma-4-12B-it-qat-4bit` | TARGET MODEL (main) | 4-bit (QAT) |
| Gemma 4 12B IT QAT Assistant | `gemma-4-12B-it-qat-assistant-4bit` | MTP DRAFTER (speculative) | 4-bit (QAT) |

### MTP Speculative Decoding Pipeline

```mermaid
graph LR
    subgraph "Drafting"
        D1["MTP Drafter predicts N tokens ahead<br/>autoregressively"]
    end
    
    subgraph "Verification"
        V1["Target model verifies all N tokens<br/>IN PARALLEL using attention"]
    end
    
    subgraph "Accept/Reject"
        AR1["Accepted tokens → direct output<br/>Rejected tokens → target generates correct"]
    end
    
    D1 --> V1 --> AR1
    
    style AR1 fill:#2d6,stroke:#333
```

**Result**: ~3x speedup, ZERO quality loss.

### KV Cache Sharing (Unified Architecture)

The drafter reuses the KV cache from the target model:
- Uses cross-attention over the target's state
- Avoids redundant pre-fill phase
- More accurate multi-token prediction

### QAT (Quantization-Aware Training)

QAT produces 4-bit models that maintain near-full-precision accuracy because quantization effects were modeled during training, not applied post-hoc. These are Google DeepMind's official quantized releases via the `mlx-community` Hugging Face organization.

### Server Configuration (mlx-vlm)

```bash
# Start the complete pipeline (target + drafter + TurboQuant KV + thinking)
bash /Users/alefita/probe/sdk-test/mlx-vlm-server.sh start
```

| Parameter | Value | Effect |
|-----------|-------|--------|
| Model (target) | `gemma-4-12B-it-qat-4bit` | Main model, verifies tokens |
| Draft model | `gemma-4-12B-it-qat-assistant-4bit` | MTP drafter, proposes tokens |
| Draft kind | `mtp` | Multi-Token Prediction mode |
| KV bits | `3.5` | TurboQuant — ~50% KV memory savings |
| KV scheme | `turboquant` | Optimized quantization scheme |
| Thinking | `--enable-thinking` | Native thought tokens |
| Keep cache | `MLX_VLM_KEEP_CACHE=1` | Persistent KV cache between requests |

Server exposes OpenAI-compatible API at:
- `http://localhost:8080/v1`
- `http://localhost:8080/health`

> **Note**: `MLX_VLM_KEEP_CACHE=1` requires manual patches on mlx-vlm and mlx-lm libraries. Not available on clean installs.

### AGY SDK Integration Path

The proper integration uses `GemmaConfig` — proto field 3 of the `HarnessConfig` oneof `model_config`:

```protobuf
message GemmaConfig {
    string base_url = 1;     // e.g., "http://localhost:8080/v1"
    string model_name = 2;   // e.g., "gemma-4-12B-it-qat-4bit"
}
```

```python
from google.antigravity import Agent
from google.antigravity.connections.local import LocalAgentConfig
from google.antigravity import types

config = LocalAgentConfig(
    gemma_config=types.GemmaConfig(
        base_url="http://localhost:8080/v1",
        model_name="gemma-4-12B-it-qat-4bit",
    ),
    system_instructions="You are a helpful assistant.",
)
async with Agent(config) as agent:
    response = await agent.chat("Hello from Gemma 4 local pipeline!")
```

This uses `GemmaConfig`, NOT `CustomBackendConfig`. The `GemmaConfig` is the dedicated proto path for local Gemma models (field 3 in the oneof). `CustomBackendConfig` (field 13) is reserved for external backends like DeepSeek v4.

### Target vs MTP Drafter Comparison

| Aspect | Target Model | MTP Drafter |
|--------|-------------|-------------|
| Role | TARGET (principal) | DRAFTER (speculative) |
| Purpose | Generate + verify tokens | Propose tokens speculatively |
| Size | Full 12B parameters | Lightweight drafter |
| Used alone? | Yes, slower | No, meaningless alone |
| Quality | Defines output quality | Does NOT affect quality |
| Speed | ~15-25 tok/s (M2 Pro) | Enables ~3x speedup |

### Performance Expectations (Apple Silicon)

| Hardware | Base (tok/s) | With MTP (tok/s) |
|----------|-------------|-------------------|
| M2 Pro/Max | ~15-25 | ~40-60 |
| M3 Pro/Max | ~20-35 | ~55-90 |
| M4 Pro/Max | ~30-50 | ~80-130 |

With TurboQuant KV cache (3.5-bit), full 256K context is available.

## Python SDK Integration

### Package Structure

```
google/antigravity/
├── __init__.py          (1.5KB)   — Public API exports
├── agent.py             (7.9KB)   — Core Agent class
├── types.py             (37.9KB)  — Type definitions (massive)
├── connections/         — External service connections
├── conversation/        — Conversation state management
├── hooks/               — Lifecycle hooks (before/after tool calls)
├── tools/               — Tool definitions and registry
├── triggers/            — Event triggers (webhooks, schedules)
└── utils/               — Utility functions
```

### Key Module: types.py (37KB)

The largest file in the SDK, containing all Pydantic models for:
- Agent configuration (model selection, temperature, max tokens)
- Conversation models (messages, tool calls, tool results)
- Tool definitions (parameter schemas, return types)
- Model info: `CustomModelInfoOverride` for routing to non-default providers
- Safety settings (content filters, harm categories)

### Core Agent Class

```python
class Agent:
    def __init__(
        self,
        model: str | CustomModelInfoOverride = "gemini-2.5-pro",
        tools: list[Tool] | None = None,
        system_instruction: str | None = None,
    ): ...

    async def send_message(self, message: str) -> AgentResponse: ...
    async def stream_message(self, message: str) -> AsyncIterator[AgentChunk]: ...
```

### Hook System

Lifecycle hooks for intercepting agent behavior:
- `before_tool_call` — modify tool inputs
- `after_tool_call` — process tool outputs
- `before_model_call` — modify model requests
- `after_model_call` — process model responses

### Current Auth Methods

| Method | When to Use |
|--------|------------|
| `GEMINI_API_KEY` env var | When no JETSKY installation exists |
| Interactive PKCE flow | First-time auth (creates the keychain entry) |
| **Keychain derivation (RFC-001)** | When JETSKY is installed and authenticated |

The keychain method should be tried FIRST, falling back to the others. See [[sdk-test-synthesis]] for the full RFC-001 specification.

## OpenCode ACP Integration

### Verified Flags

```bash
opencode acp [options]
--port         port to listen on              [number] [default: 0 = random]
--hostname     hostname to listen on          [string] [default: "127.0.0.1"]
--mdns         enable mDNS service discovery  [boolean] [default: false]
--mdns-domain  custom domain for mDNS         [string]
--cors         additional CORS domains        [array]
--cwd          working directory              [string]
--print-logs   print logs to stderr           [boolean]
--log-level    log level                      [string] DEBUG|INFO|WARN|ERROR
```

**Key Finding**: `opencode acp --port 8765` starts an HTTP server on the specified port. The presence of `--hostname`, `--cors`, and `--port` flags confirms HTTP transport.

### NOT Supported on `acp`

- `--session-id` (does not exist)
- `--provider` (does not exist)
- `--model` (does not exist)

### Session Management for Scripted Use

```bash
opencode run -s <session-id> "prompt here"
opencode run -m "opencode/deepseek-v4-flash-free" "prompt here"
opencode run -m "model" --variant high "prompt"
```

### ACP Protocol Transport

- **Protocol**: JSON-RPC 2.0 over stdio (newline-delimited)
- **Transport**: stdin/stdout of the subprocess
- **Session state**: Maintained in memory by the ACP server; written to `~/.local/share/opencode/` on disk

## Deep-Dive Pages

| Topic | Deep-Dive Page | Key Content |
|-------|---------------|-------------|
| DeepSeek + Heartbeat | [[sdk-test-deepseek-heartbeat]] | DeepSeek V4 integration details, Heartbeat Protocol, Proto-Unicode sequences, token refresh mechanism |
| Auth chain | [[sdk-test-auth-chain]] | TrySilentAuth flow, keychain format, passive refresh mechanics |
| Localharness | [[sdk-test-localharness]] | How model configs are passed to the harness via HarnessConfig |
| Protobuf | [[sdk-test-protobuf]] | CustomBackendConfig and GemmaConfig message definitions |
| Decompiled patterns | [[sdk-test-decompiled-patterns]] | Battle Mode (multi-model A/B testing), MCP Integration pattern |

## Cross-References

- [[sdk-test-antigravity-sdk]] — Full SDK reference (Agent, Conversation, types, tools, hooks, triggers)
- [[sdk-test-reverse-engineering]] — Binary analysis that revealed the auth chain and enum structures
- [[sdk-test-architecture]] — Full architecture synthesis (auth chain, token lifecycle, gRPC)
- [[sdk-test-synthesis]] — Epiphany synthesis, RFC-001, and preprocessor workflow
- antigravity-2.0 — The broader Antigravity platform
- [[co-scientist]] — The Co-Scientist multi-agent system