4.11 MarketOntologyBuilder

1. Bot Identity

2. Purpose

Cluster markets into events, themes, and underlying entities for cross-market reasoning.

3. Why This Bot Matters

• Cross-market correlation invisible to Risk

  Without an ontology, PortfolioGuard sees fifty independent markets where the underlying ontology says they all resolve on the same NFL game. Aggregate exposure to a single real-world event is then dramatically under-counted.

• Strategies can't compose multi-market positions

  Cross-market arbitrage and hedging strategies need a structured map of which markets share an underlying. Hand-curated lists drift; a generated ontology stays in sync as new markets list each day.

• Search and discovery degrade as the catalogue grows

  With ten thousand listed markets and no ontology, MarketScanner becomes a substring search. Themed events and entity-level queries — 'all markets resolving on US election' — require structured clusters.

• Reconciliation can't verify outcome correctness

  When a real-world event fires, gov.reconciler needs to confirm every market that should have resolved did. Without an ontology mapping events to markets, that check is manual.

4. Required Polymarket Inputs

5. Required Internal Inputs

6. Parameter Guide

7. Detailed Parameter Instructions

{ "build_interval_s": 3600 }

if (p.build_interval_s > p.hard) throw ConfigError('PARAMETER_CHANGE_REQUIRES_APPROVAL');

{ "min_market_count": 50 }

if (markets.length < p.min_market_count.hard) emit('STALE_DATA');

8. Default Configuration

{
  "bot_id": "intel.marketontologybuilder",
  "version": "0.1.0",
  "mode": "planned",
  "defaults": {
    "build_interval_s": 3600,
    "min_market_count": 50
  },
  "locked": {
    "build_interval_s": {
      "max": 86400
    },
    "min_market_count": {
      "min": 5
    }
  }
}

9. Implementation Flow

— not yet authored —

10. Reference Implementation

Pseudocode is language-agnostic. FETCH = read input. EMIT = produce output. IF/THEN/ELSE = decision. Translate directly to TypeScript, Python, Go, or Rust.

FUNCTION buildOntology():
  // 0. KillSwitch check
  IF FETCH internal.killswitch.status == ACTIVE:
    RETURN

  // 1. Fetch all active markets from Gamma
  markets = FETCH gamma.GET('/markets?status=active&limit=500')
  IF len(markets) == 0:
    EMIT WARN 'STALE_DATA'
    RETURN

  // 2. Cluster by tag/category
  ontology = {}
  FOR m IN markets:
    FOR tag IN m.tags:
      ontology[tag] = ontology.get(tag, []) + [m.condition_id]

  // 3. Build relationship graph
  graph = buildRelationshipGraph(ontology, markets)

  // 4. Compute ontology_hash
  new_hash = hash(ontology)
  IF new_hash == last_ontology_hash:
    RETURN  // no change

  // 5. Emit ObservationReport
  EMIT ObservationReport {
    report_id: gen_id(),
    kind: 'ObservationReport',
    ontology_hash: new_hash,
    category_count: len(ontology),
    market_count: len(markets),
    emitted_at_ms: now_ms()
  }
  last_ontology_hash = new_hash

SDK calls used

• gamma.GET('/markets?status=active&limit=500')
• data.GET('/tags')
• internal.killswitch.status

Complexity: O(M*T) per build cycle where M = markets, T = average tags per market

11. Wire Examples

Input — what arrives on the wire

{
  "label": "Active markets list from Gamma for ontology build",
  "source": "gamma",
  "payload": {
    "market_count": 312,
    "categories": [
      "politics",
      "crypto",
      "sports",
      "economics"
    ],
    "timestamp_ms": 1746703000000
  }
}

Output — what the bot emits

{
  "label": "ObservationReport — ontology updated",
  "payload": {
    "report_id": "rep_mob_1746703000000",
    "trace_id": "trc_0xbeef0102030405060712",
    "bot_id": "intel.marketontologybuilder",
    "kind": "ObservationReport",
    "ontology_hash": "0xdeadbeef12345678",
    "category_count": 18,
    "market_count": 312,
    "emitted_at_ms": 1746703020000
  }
}

12. Decision Logic

13. Standard Decision Output

This bot returns a RiskVote object. See RiskVote schema.

{
  "report_id": "rep_mob_1746703000000",
  "trace_id": "trc_0xbeef0102030405060712",
  "bot_id": "intel.marketontologybuilder",
  "kind": "ObservationReport",
  "ontology_hash": "0xdeadbeef12345678",
  "category_count": 18,
  "market_count": 312,
  "warnings": [],
  "emitted_at_ms": 1746703020000
}

14. Reason Codes

15. Metrics & Logs

Metrics emitted

Alerts

Dashboards

• Grafana — Intelligence / MarketOntologyBuilder market and category count over time

16. Developer Reporting

{
  "bot_id": "intel.marketontologybuilder",
  "ontology_hash": "0xdeadbeef12345678",
  "category_count": 18,
  "market_count": 312,
  "build_duration_ms": 4200,
  "ontology_changed": true,
  "killswitch_active": false
}

17. Plain-English Reporting

18. Failure-Mode Block

19. Failure-Injection Recipes

20. State & Persistence

Cold-start recovery

On cold start, trigger full rebuild on first cycle; last snapshot may be stale.

21. Concurrency & Idempotency

22. Dependencies

Depends on (must run first)

Emits to (downstream consumers)

Sibling bots (same OrderIntent)

External services

23. Security Surfaces

Abuse vectors considered

• Gamma API returns a truncated market list causing category count drop and false TAG_COUNT_DROP alerts
• Adversary adds misleading tags to markets to skew category ontology

Mitigations

• TAG_COUNT_DROP guard prevents replacing good ontology with truncated data
• Ontology is informational only; strategies validate independently before acting on category signals

24. Polymarket V2 Compatibility

API surfaces declared

Networks supported

25. Versioning & Migration

Migration history

26. Acceptance Tests

Unit Tests

Integration Tests

Property Tests

27. Operational Runbook

MarketOntologyBuilder incidents are typically Gamma API outages or truncated responses. Stale ontology does not block trading but may reduce category signal quality.

On-call actions

Manual overrides

• force_rebuild — POST /internal/marketontologybuilder/rebuild to trigger an immediate full rebuild — After Gamma API recovery or known category structure changes

Healthcheck

Endpoint: /internal/health/marketontologybuilder | Green: Last build < 2 h ago AND Redis reachable AND Gamma API returning 200 | Red: No successful build for > 2 h OR Redis unreachable

28. Promotion Gates

A bot does not advance to the next readiness state until every gate below is green. Gates are observable from production data — no subjective sign-off.

Promote to Shadow

Promote to Limited live

Promote to General live

29. Developer Checklist

Ready-to-ship score: 27/27 sections complete · 100%