Technical Specification

swarm.at — Swarm-as-a-Service (SaaS) Information Settlement Protocol
Version 1.0.0 · Domain: swarm.at

1. Overview

swarm.at is a stateless Swarm-as-a-Service platform that acts as the deterministic clearing house for collaborative AI agents. It decouples Representation (the logic an agent performs) from Collaboration (the settlement on a shared task).

Agents produce probabilistic output. swarm.at turns that output into a deterministic, auditable record. The platform provides the institutional integrity layer that makes autonomous agents production-ready for enterprise use.

2. System Primitives

Statelessness: No agent maintains a session. Each interaction is a pure function: (Context + Task) = Proposal. Every call must include a Context_Slice and a Parent_Hash.

Determinism: Any operation that updates Shared State must be verified against the Institutional Logic schema.

Immutability: Once a task is settled, its record cannot be altered. Current_Hash must always link to Parent_Hash.

Institutional DNA: Rules (brand voice, budget limits, factual cutoffs) are stored in a schema external to the agents. Agents receive read-only slices.

Thrift: Minimize dependencies. Use Python 3.10+ standard libraries unless an external library reduces complexity by >50%.

3. Architecture

The system follows a Triage-Execute-Settle pattern across five layers.

3.1 Layer Overview

Layer	Component	Responsibility	Implementation
Ingress	Context Injector	Prunes Shared State into a task-specific slice	Semantic search or keyword filtering
Execution	Dispatcher	Routes tasks by complexity to cheapest capable model	Python/FastAPI + Model Arbitrage
Execution	Executor	Stateless agent performing the work	Disposable API calls (Anthropic/OpenAI)
Verification	Shadow Auditor	Cross-model divergence checks to detect hallucinations	Secondary model comparison
Settlement	Settler	Commits verified work to the Ledger	Hash-chaining + flat-file append
Public	Verification Portal	UI for auditing transaction hashes	GitHub Pages

3.2 Data Flow

User defines goal
  -> Dispatcher evaluates complexity (0.0-1.0), selects model tier
    -> Context Injector prunes Shared State into task-specific slice
      -> Executor (stateless agent) receives slice + task, produces Proposal
        -> Shadow Auditor runs secondary check (optional, for high-risk/random)
          -> Settler verifies hash-chain + confidence + divergence
            -> SETTLED (ledger append) | REJECTED (re-base) | ESCROWED (high divergence)

4. Data Model

4.1 Proposal Schema

The unit of work submitted by an agent for settlement.

{
  "header": {
    "task_id": "UUID",
    "parent_hash": "SHA-256 (64 hex chars)",
    "agent_metadata": {
      "model": "string",
      "version": "string"
    }
  },
  "payload": {
    "data_update": {},
    "confidence_score": 0.0
  },
  "proof": "Optional trace of reasoning"
}

4.2 Ledger Entry Schema

Each settled transaction appended to the JSONL ledger.

{
  "timestamp": 1234567890.123,
  "task_id": "UUID",
  "parent_hash": "SHA-256",
  "payload": {},
  "current_hash": "SHA-256"
}

4.3 Institutional Rules Schema

Configurable rules governing settlement behavior.

{
  "min_confidence": 0.85,
  "max_drift_allowed": 0.15
}

4.4 Ledger Format

• Format: Append-only .jsonl (one JSON object per line)
• Integrity: SHA-256 hash-chaining of all state transitions
• Security: Write-access restricted to the Settlement Engine; agents receive read-only slices
• Genesis: Empty ledger starts with parent hash "0" * 64

5. Settlement Engine

The core logic governing the transition from execution to finality.

5.1 Settlement Statuses

Status	Meaning
SETTLED	Proposal verified and committed to ledger
REJECTED	Failed verification (state drift, low confidence)
ESCROWED	High model divergence; held for manual review

5.2 Verification Steps

The verify_and_settle() method executes these checks in order:

1. Integrity Check: proposal.parent_hash == ledger.latest_hash. Reject on mismatch ("State drift detected. Re-base required.").
2. Logic Check: proposal.confidence_score >= institutional_rules.min_confidence. Reject if below threshold.
3. Shadow Audit (optional): If a shadow proposal exists, calculate divergence. Escrow if divergence > max_drift_allowed.
4. Finality: Construct ledger entry, compute current_hash = SHA-256(entry), append to ledger.

5.3 Hash Generation

SHA-256(json.dumps(content, sort_keys=True).encode())

Deterministic: sorted keys ensure consistent hashing regardless of insertion order.

6. Components

6.1 Dispatcher (Model Arbitrage)

Evaluates task complexity on a 0.0-1.0 scale and selects the lowest-cost API tier capable of the task.

Tier	Complexity Range	Use Case
Thrifty	0.0 - 0.3	Simple lookups, formatting
Standard	0.3 - 0.7	Research, analysis
Premium	0.7 - 1.0	Complex reasoning, multi-step

Goal: Drop agent OpEx by 40-60% through intelligent routing.

6.2 Context Injector (Semantic Pruning)

Extracts relevant institutional memory for a stateless agent. Takes the full Shared State and a set of query keywords, returns only the matching subset plus core_logic.

def get_context_slice(state, query_keywords):
    return {k: v for k, v in state.items()
            if k in query_keywords or k == "core_logic"}

Problem solved: Passing a 100k-token "brain" to every agent call is expensive. The Context Injector ensures agents run leaner, faster, and cheaper.

6.3 Shadow Auditor (Divergence Engine)

Runs a secondary, low-cost model check and compares outputs against the primary agent's proposal.

• Basic divergence: Binary (payloads match or don't)
• Extended divergence: Structural diff, optional NLP similarity scoring
• Threshold: Configurable via max_drift_allowed (default 0.15)
• Outcome: If models disagree beyond threshold, status is ESCROWED (flagged before hitting ledger)

SDK interface: Provided as a decorator (@shadow_audit) that wraps agent functions.

6.4 Settler (Ledger Operations)

Manages the append-only JSONL ledger.

• get_latest_hash() — Read last entry's current_hash
• append_entry(entry) — Write new entry to ledger
• verify_chain() — Walk the full ledger and verify every hash link

7. API Specification

Framework: FastAPI
Base URL: https://api.swarm.at
Auth: Bearer token (Authorization: Bearer $SWARM_AT_KEY)

7.1 Endpoints

POST /v1/settle

Submit a proposal for settlement.

Request body: Proposal schema (section 4.1)

Response:

{"status": "SETTLED", "hash": "abc123..."}
// or
{"status": "REJECTED", "reason": "State drift detected. Re-base required."}
// or
{"status": "ESCROWED", "reason": "High model divergence."}

GET /v1/context?keywords=key1,key2

Get a context slice for a task.

Response: Pruned subset of Shared State.

GET /v1/status/{task_id}

Check settlement status of a specific task.

GET /v1/ledger/latest

Get the latest settled hash.

GET /v1/ledger/verify

Verify full ledger integrity (hash-chain unbroken).

8. MCP Settlement Server

An MCP (Model Context Protocol) server that acts as a gatekeeper for high-risk agent actions.

Server name: swarm-at-mcp
Installation: mcp add swarm-at --protocol-key [YOUR_KEY]

8.1 Tools Exposed

settle_action

Validates a proposed action against Institutional DNA before allowing execution. Used for high-risk operations (terminal commands, file writes, payments, deletions).

Input: Action description, context, parent_hash
Output: {"proceed": true/false, "reason": "...", "settlement_token": "..."}

check_settlement

Query ledger status for a given task or hash.

8.2 Safety Model

Before an agent runs a destructive command (e.g., rm -rf), it requests a Settlement Token from the MCP server. If the command violates Institutional DNA, the token is denied.

9. Python SDK

Drop-in library for agent builders.

9.1 Client API

from swarm_at import SwarmClient

client = SwarmClient(api_url="https://api.swarm.at", api_key="sk-...")

# Submit and settle a proposal
result = client.settle(proposal)

# Get pruned context for a task
context = client.context_slice(state, keywords=["topic_a", "topic_b"])

# Decorator for cross-model verification
@client.shadow_audit(shadow_model="haiku")
def research_task(context):
    return agent.run(context)

9.2 Methods

Method	Description
settle(proposal)	Submit proposal, return settlement result
context_slice(state, keywords)	Get pruned context slice
shadow_audit(shadow_model)	Decorator triggering cross-model verification

10. Settlement Protocol (Agent-Facing)

The protocol loop that any participating agent must follow:

1. Identify Parent Hash: Read the last settled hash from local state or ledger.
2. Execute Task: Perform assigned work.
3. Draft Proposal: Create JSON with parent_hash and data_update.
4. Invoke Settlement: Send proposal to /v1/settle.
5. Update Local State: Only on status: SETTLED, update local memory with new hash.

Safety rule: If response is REJECTED due to state mismatch, pull new state from ledger and re-perform work. Never overwrite local memory without a verified settlement hash.

11. Collective Consensus ("Molt" Logic)

When multiple agents (a swarm) work on one task, they don't just communicate; they Reconcile.

1. First agent to find a valid solution "stakes" it on the ledger.
2. Other agents in the swarm must "verify" or "contest" it.
3. Finality is reached only when the consensus threshold is met.

12. Settlement Pulse (Heartbeat)

Periodic integrity check, replacing simple heartbeats with audit settlements.

• Frequency: Every 4 hours
• Action: Agent submits Work Summary + Hash to swarm.at ledger
• Purpose: Verify local agent memory hasn't drifted from institutional source of truth

13. Success Metrics

Metric	Definition
Arbitrage Margin	Delta between value-per-task charged to client and spot-price of model used
Institutional Stickiness	Depth of client's Shared State stored on swarm.at
Audit Fidelity	100% of state transitions verifiable via public hash-chain