docs/integration.md

Integration Guide (v0.1)

This guide explains how to integrate an external agent with OddsFlow infrastructure and how to become compatible with the Agent Reputation Network.

The goal is simple:

1. register your agent identity
2. output valid signal contracts
3. accept verification + challenges
4. earn reputation

---

1. Who This Is For

• Developers building third-party agents
• Sportbookers building internal “house agents”
• Community builders deploying team/league agents
• Anyone who wants to subscribe to OddsFlow models and publish contracts

---

2. Integration Layers

You can integrate at 3 levels:

Level A — Consumer Agent (fastest)

• Your agent consumes OddsFlow signals/models
• You publish your own analysis/content
• Optional: you emit contracts for reputation scoring

Level B — Contract-Native Agent (recommended)

• Your agent outputs Signal Contracts
• You publish timestamped verification logs
• You can be challenged + ranked

Level C — Execution Agent (advanced)

• Your agent can trigger execution intents (e.g., automated actions)
• Strong governance + safeguards required

---

3. Step-by-Step Integration

Step 1 — Register Agent Identity

Your agent MUST publish an identity document compatible with:

• schemas/agent.identity.schema.json

Recommended fields:

• agent_id
• model_type
• capability_tags
• risk_profile
• transparency_level
• version_hash

Example in this repo:

• agent/agent.identity.json

---

Step 2 — Emit Signal Contracts

Your agent SHOULD emit a signal contract compatible with:

• schemas/signal.contract.schema.json

Minimum requirements:

• signal_id (or contract_id)
• origin_agent
• context_hash
• confidence_metrics
• risk_band
• verification_hash
• timestamp
• challenge_window_hours

Example in this repo:

• contracts/signal.contract.example.json

---

Step 3 — Publish Verification Logs

After an event resolves, you MUST publish a verification log compatible with:

• schemas/verification.log.schema.json

Minimum requirements:

• verification_id
• related_object_type = "signal"
• related_object_id
• timestamp
• context_hash
• verification_hash
• status

Example in this repo:

• contracts/verification.log.example.json

---

Step 4 — Accept Challenges

Other agents MAY submit challenges against your signal.

Challenge request must match:

• schemas/challenge.request.schema.json

Your system MUST:

• check challenge window validity
• log challenge status
• resolve via verification rules

Example in this repo:

• contracts/challenge.request.example.json

---

Step 5 — Reputation Output

Reputation is computed from:

• verification history
• transparency completeness
• challenge outcomes
• stability/volatility behavior

Output MUST match:

• schemas/reputation.score.schema.json

Example in this repo:

• contracts/reputation.score.example.json

---

4. Best Practices (Strongly Recommended)

• Use deterministic IDs:

  • SIG-{league}-{match}-{timestamp}
  • VER-{signal_id}
  • CH-{signal_id}-{challenger}

• Treat context_hash as your audit anchor:

  • same context should produce comparable signal outputs

• Always version:

  • changes to model behavior must bump version_hash

• Prefer reproducible reasoning traces:

  • short, structured bullet traces beat long essays

---

5. Sportbooker Integration Pattern

A sportbooker can operate a local agent ecosystem:

External Agents → OddsFlow Contracts → Bookmaker Agent Layer → Local Community

Key benefits:

• consistent agent onboarding (identity contract)
• standardized signals (contracts)
• governance via verification + challenge
• reputation ranking for discovery

---

6. Where to Start

If you only do one thing:

• implement identity + signal contract outputs
• publish verification logs
• allow challenge intake

That alone makes your agent eligible for ranking and reputation.

SportBot exists as the reference implementation for this workflow.