Autonomous. Discerning. Virtuous.

Autonomous critical-thinking platform that extracts entities, reasons over knowledge graphs, and generates intervention strategies — all driven by Gemini 3.

Unsprawl ships 8 missions spanning legal defense, child safety, immigration, and civil rights. Each mission is a self-contained manifest: JSON Schema entities, OWL-RL ontology rules, Z3 constraints, and data source definitions. No code changes required to add a new domain — just a new manifest.json.

Built for the Gemini 3 Hackathon.

A single unsprawl wow command runs the full autonomous pipeline end-to-end:

Phase 1  Entity Extraction ──── Gemini function_calling + JIT tool generation
    │
Phase 2  Reasoning ───────────── OWL-RL closure → SPARQL rules → Z3 constraint solving
    │
Phase 3  Deep Research ───────── Google Search grounding + thought signature continuity
    │
Phase 4  Strategy ────────────── Structured JSON generation with response_schema
    │
Phase 5  Pattern Detection ───── Cross-case SPARQL joins detect shared adversaries
    │
Sweep    Mission Sweep ───────── Runs extraction across 3 additional missions
    │
Summary  Gemini Integration ──── Token breakdown, features used, thought chains carried

Every Gemini API call prints a [GEMINI] label with the feature used, tokens consumed, and thinking level — making integration depth visible in the demo video.

Unsprawl uses 6 distinct Gemini 3 capabilities across the pipeline, not just chat completion:

Gemini-as-Judge gates local model training: the TrainerActor samples 20 training pairs, sends them to Gemini for quality scoring, and rejects batches below 70% approval before QLoRA fine-tuning proceeds.

Four engine actors communicate exclusively through NATS JetStream — no direct imports between engines:

flowchart TB
    subgraph bus["NATS JetStream — mission.{id}.{engine}.*"]
        direction LR
        B[Control Bus]
    end

    MC[Mission Control] -->|Genesis Charter| B

    B --> R["Refinery
    Entity extraction
    ProvenanceGuard
    Hippocampus"]

    B --> S["Sentinel
    Fact validation
    Safety vetoes"]

    B --> SO["Solver
    Intervention plans
    Wrangler artifacts"]

    B --> O["Orchestrator
    Session state
    Tick loop"]

    B --> T["Trainer
    Gemini-as-Judge
    QLoRA fine-tuning"]

    R -->|ExtractResult| B
    S -->|ValidateResult| B
    SO -->|InterventionPlanResult| B
    O -->|SessionStateUpdate| B
    T -->|AdapterUpdate| B

sequenceDiagram
    participant MC as Mission Control
    participant R as Refinery
    participant PG as ProvenanceGuard
    participant S as Sentinel
    participant SO as Solver
    participant W as Wrangler
    participant T as Trainer

    MC->>R: ExtractCommand (Genesis Charter)
    R->>R: Gemini function_calling → entities
    R->>PG: filter_ingest (credibility gate)
    PG-->>R: Enriched facts (score, tier, reason)
    R->>S: ExtractResult
    S->>S: Validate facts + safety checks
    S-->>T: Vetoed facts (negative DPO signal)
    S->>SO: ValidateResult (approved facts)
    SO->>SO: OWL-RL → SPARQL → Z3 → strategy
    SO->>W: Generate artifacts (PDFs, code)
    W->>W: Gemini codegen → sandbox → self-heal
    SO->>MC: InterventionPlanResult
    T->>T: Gemini-as-Judge → QLoRA → hot-swap adapter

The reasoning layer combines three formal systems — none of this is prompt engineering:

OWL-RL Inference — rdflib + owlrl compute the deductive closure over extracted entities. Inverse properties (belongsToCase), transitive relations, and class hierarchies are inferred automatically from the manifest ontology.

SPARQL Rules — Manifest-defined queries run against the closed knowledge graph. Example from Aegis:

SELECT ?case ?adversary WHERE {
  ?case1 :hasAdversary ?adversary .
  ?case2 :hasAdversary ?adversary .
  FILTER(?case1 != ?case2)
}

This detects when two unrelated tenants face the same landlord — a pattern invisible to keyword search.

Z3 Constraints — SMT formulas from strategy_constraints block gate which strategies are valid. Example: DEFEND only if arrears_amount < 25000. The solver proves satisfiability, not just checks conditions.

Each mission is a complete domain defined by a single manifest.json — entities, ontology, rules, constraints, data sources, and safety vetoes:

Adding a new mission requires zero code changes — create missions/{name}/manifest.json with your entities, rules, and constraints.

Every fact entering the knowledge graph passes through ProvenanceGuard, a credibility gate that prevents hallucinated or adversarial data from contaminating reasoning:

• Static domain classification — reuters.com (Tier 5: Verified), reddit.com (Tier 3: 2x corroboration), theonion.com (Tier 0: Satire)
• LLM fallback — Unknown domains classified by Gemini for tone/credibility
• Dispute-driven learning — Downstream engines call dispute(domain, penalty) when facts fail validation; penalties accumulate with 30-day half-life decay
• Hard gate — Facts scoring below 0.5 are rejected and warnings published to sys.warn.provenance

No external code can inject data that bypasses this filter. The extension model is manifests, not plugins.

The Wrangler takes high-level plans and autonomously generates working artifacts (PDFs, infographics, data adapters):

1. Gemini codegen — Generates complete Python scripts from plan descriptions
2. Sandboxed execution — Runs in subprocess with 60s timeout, AST-based security scanning
3. Metacognition loop — On failure, feeds the traceback back to Gemini for self-repair (up to 3 retries with adaptive temperature 0.2 → 0.8)
4. Smart AST fixes — Targeted repairs (e.g., deprecated API patterns) before full regeneration
5. Code cache — SHA256 content-hash deduplication avoids regenerating identical plans

Security guardrails block os.system, subprocess.Popen, exec(), eval(), and __import__ at both regex and AST levels.

Real-time voice interface built on LiveKit + Gemini Live:

Browser/Mic → LiveKit Room → Gemini Live (STT/TTS) → NATS Bus → Engine Actors
                                                                       ↓
                                                        Response → TTS → Speaker

• Speaker verification — SpeechBrain X-vector embeddings, enrollment in 14 languages
• Emotion tracking — Audio-based emotion detection for adaptive responses
• Turn prediction — Voice Activity Projection (VAP) model for interruption-free conversation
• Conversation naturalness — Backchannel generation ("mm-hmm"), disfluency injection, adaptive timing
• Avatar support — FaceFormer (CPU) → blend shapes → TalkingHead (browser WebGL, zero GPU required)

unsprawl/
├── cli.py                          # CLI commands including `wow` pipeline
├── api.py                          # FastAPI app, WebSocket endpoints, tick loop
├── core/
│   ├── factory.py                  # EntityFactory — JIT tool generation from manifests
│   ├── deep_research.py            # Gemini Deep Research API integration
│   ├── rate_limiter.py             # gated_generate — chokepoint for all Gemini calls
│   ├── observability.py            # OpenTelemetry + Logfire instrumentation
│   └── messages.py                 # Pydantic message schemas (control bus)
├── engines/
│   ├── refinery/
│   │   ├── actor.py                # Entity extraction, collection, local LLM
│   │   ├── provenance.py           # ProvenanceGuard (memory firewall)
│   │   └── hippocampus.py          # In-memory fact store
│   ├── sentinel/
│   │   └── actor.py                # Fact validation, safety vetoes
│   ├── solver/
│   │   ├── actor.py                # OWL-RL + SPARQL + Z3 → intervention plans
│   │   ├── wrangler.py             # Self-healing artifact generator
│   │   └── armory.py               # DuckDB artifact storage
│   ├── trainer/
│   │   └── actor.py                # Gemini-as-Judge, QLoRA fine-tuning, DPO
│   └── orchestrator/
│       ├── actor.py                # Session state management
│       └── mission_control.py      # Mission loading, genesis event
├── missions/
│   ├── aegis/manifest.json         # Legal Defense
│   ├── amber/manifest.json         # Child Safety
│   ├── chronicle/manifest.json     # Language Preservation
│   ├── compass/manifest.json       # Foster Youth
│   ├── nightshift/manifest.json    # Education & Family Law
│   ├── sanctuary/manifest.json     # Immigration Defense
│   ├── shield/manifest.json        # ICE Raid Response
│   ├── watchlist/manifest.json     # Gang Database Defense
│   └── wow_fixtures.py             # Demo fixture data per mission
├── voice/
│   ├── pipeline.py                 # LiveKit + Gemini Live voice agent
│   └── speaker_verify.py           # SpeechBrain X-vector enrollment
├── data_sources/
│   ├── adapters/                   # REST, GraphQL, scraper, static adapters
│   └── registry.py                 # Adapter registration and discovery
└── simulation/
    └── advect.py                   # NVIDIA Warp differentiable physics

web/                                # React frontend (Kedro-Viz + xterm.js console)

• Docker with NVIDIA Container Toolkit (GPU access)
• A Gemini API key (GEMINI_API_KEY)
• Python 3.12+ and uv

The deploy command handles everything: preflight checks, config generation, Docker orchestration, and optional Cloudflare Tunnel setup.

# 1. Clone and install
git clone https://github.com/unsprawl/unsprawl.git
cd unsprawl
uv pip install -e ".[engine]"

# 2. Set your API key
cp .env.example .env
# Edit .env — set GEMINI_API_KEY (required), LOGFIRE_API_KEY (optional)

# 3. Deploy locally
unsprawl deploy localhost --no-tunnel

# Or deploy to a public domain with Cloudflare Tunnel
unsprawl deploy unsprawl.io --install

# Or deploy without GPU
unsprawl deploy myapp.dev --no-tunnel --cpu

unsprawl deploy will:

1. Run preflight checks (Docker, GPU/CUDA, cloudflared)
2. Auto-install missing prerequisites when --install is passed
3. Generate .env, Caddyfile, livekit.yaml, and cloudflared.yml from the domain
4. Generate a CPU-only compose override if no GPU is detected (or --cpu)
5. Provision LiveKit TLS certs and install renewal cron (remote deploys)
6. Start all 13 Docker services via docker compose up

Voice UI is opt-in: docker compose --profile voice-ui up

cp .env.example .env
# Edit .env — set GEMINI_API_KEY
docker compose up --build

uv pip install -e ".[engine]"
export GEMINI_API_KEY=your-key-here
unsprawl wow --mission aegis

For voice: uv pip install -e ".[voice]" and a running LiveKit + NATS instance.

The primary demo path — runs the full autonomous pipeline in your terminal:

# Inside the API container (recommended)
docker exec -it unsprawl-api-1 python -m unsprawl.cli wow aegis

# Or locally if installed
unsprawl wow --mission aegis

This runs all 7 phases end-to-end: entity extraction, OWL-RL reasoning, deep research, strategy generation, pattern detection, mission sweep, and Gemini integration summary. Every Gemini API call prints a [GEMINI] label with the feature used and tokens consumed.

# Any of the 8 missions
unsprawl wow --mission amber      # Missing child response
unsprawl wow --mission sanctuary  # Immigration defense
unsprawl wow --mission shield     # ICE raid response
unsprawl wow --mission compass    # Foster youth
unsprawl wow --mission chronicle  # Language preservation
unsprawl wow --mission nightshift # Education & family law
unsprawl wow --mission watchlist  # Gang database defense

# Start the voice agent (inside Docker)
docker compose --profile voice-ui up

# Open the voice frontend
# https://unsprawl.io/voice (production) or http://localhost:3001 (local)

Speak naturally — the agent uses Gemini Live for real-time speech-to-speech, with speaker verification, emotion tracking, and document OCR via the camera feed.

Navigate to http://localhost (or https://unsprawl.io in production). The dashboard shows the knowledge graph, pipeline DAG, dataset grid, and live WebSocket streaming from the API.

Built for the Gemini 3 Hackathon. All AI powered by Gemini 3.