Aloo Paratha
Multi-agent handoffs today rely on flat prose summaries.
Core trick
Aligns graph-attention task embeddings with agent action traces; rejects actions only when a symbolic check names the violated edge.
Description
Multi-agent handoffs today rely on flat prose summaries. This lossy projection discards structural graph dependencies and resource constraints, forcing receiving agents to guess step order and rules. This causes a 51.3% failure rate under task-specification constraints. Appending growing conversational histories also causes severe KV-cache pollution and context bloat.
The Solution (Mao)
Mao is a plug-and-play middleware SDK that replaces prose handoffs with a joint structural-semantic vector space (128-dimensional). It projects a relation-aware graph attention network (R-GAT) representation of the active task frontier and aligns it contrastively with agent reasoning traces using a triplet margin loss. This clusters valid actions close to the graph state while pushing violating actions far away.
Local Safety & Witness-Routing
At runtime, Mao measures the cosine similarity between the graph and the proposed action. For safety, it uses a hybrid neuro-symbolic gate called witness-routing. An action is only rejected if the neural gate fires and the symbolic graph checker can name the specific violated constraint edge. This ensures a flawless gating precision of 1.000. On rejection, local Gemma 4 (via Ollama) translates raw topological violations into natural-language replan instructions.
Key Metrics (n=300 held-out samples)
Baseline Prose Handoff Success: 48.7%
Mao Local Offline Success: 99.7% with a median latency of 1.7 ms.
Mao Gemini Cloud Success: 99.3% with a median latency of 527 ms.
Zero-Shot Domain Generalization (LOTO): Averages 95.1% success on unseen workflows.
Out-of-Distribution Safety: Deferral rate safely climbs from 6% to 62% under domain shift rather than failing silently, keeping precision at 1.000.000 precision everywhere.
README excerpt
# Joint-Embedding Handoff Structural-semantic alignment for multi-agent orchestration. Built for the Google DeepMind Bangalore Hackathon, Problem Statement 2 (iAPI and Managed Agents) and the Gemma local-first track. Multi-agent handoff today is a prose summary. That summary is a lossy projection of a structured object (the task-execution graph) onto a sentence, and the receiving agent has to re-infer structure from text with no fidelity guarantee. I replace prose handoff with a joint structural-semantic embedding: a relation-aware GNN over the live task graph, contrastively aligned with agent reasoning traces. Every proposed action is then checked by a local, on-device cosine-similarity adjudicator backed by Gemma 4. Full experimental setup and results are in [docs/experiments.md](docs/experiments.md). ## Quickstart ``` pip install -r requirements.txt python -m mao.train # about 70s on CPU: datagen, contrastive training, tau calibration python -m mao.eval # constraint-respecting handoff rate, naive vs joint-embedding python -m demo.swe_scenario # branch-before-QA terminal demo (add --fast to skip pauses) python -m demo.web.server # live split-screen web demo at http://127.0.0.1:8765 ``` No API key or local model is required for the core pipeline: the language encoder falls back to a deterministic local featurizer, and the adjudicator's decision is plain vector math. With `GEMINI_API_KEY` set (in `.env`), trace embedding uses the Gemini emb