[WIP] Corgent API Spec (Draft v0.1)

THIS SPEC IS A DRAFT. NAMES AND FIELDS MAY CHANGE AS VIRTUAL SDK AND CORTENSOR TESTNET PHASE 3–4 HARDEN.

0) Purpose

Corgent is a Virtual ecosystem service agent that provides:

1. Delegation-as-a-Service (Compute Oracle)

2. Validation-as-a-Service (Result Oracle)

3. Arbitration-as-a-Service (Dispute Oracle)

Corgent sits client/router-side and uses Cortensor to run redundant inference and produce PoI/PoUW-backed verification artifacts. (Cortensor)

---

1) Surfaces

Corgent exposes two integration surfaces:

A. GAME Worker/Function Surface (Virtual SDK)

Corgent is callable as a Function target from a GAME Worker. The Virtual SDK is built around Agent → Worker → Function. (GitHub)

B. ACP Marketplace Surface (Virtual ACP)

Corgent can act as an ACP Evaluator / Oracle Seller:

• Buyers request verification or arbitration.

• Sellers may optionally request pre-verification. ACP role model: Buyer (Client), Seller (Provider), optional Evaluator. (Virtuals Protocol)

---

2) Core Concepts

2.1 Task

A unit of work to run or verify.

{
  "task_id": "uuid",
  "type": "inference | validation | arbitration",
  "input": { "prompt": "...", "params": {...} },
  "claimed_result": { "output": "...", "metadata": {...} }, 
  "spec": { "schema": "...", "constraints": {...} }
}

• claimed_result only required for validation/arbitration.

2.2 Policy / Tier

{
  "policy": "fast | safe | oracle | adaptive",
  "redundancy": 1,
  "min_confidence": 0.75,
  "max_retries": 2,
  "model_pref": "auto | model_id",
  "sla_tier": "standard | high_reliability | low_latency"
}

Tiers map to redundancy + scoring depth (as you described). SLA weighting is aligned with NodePool/SLA routing direction in Testnet. (Cortensor)

2.3 Verdict

{
  "status": "VALID | INVALID | RETRY | NEEDS_SPEC",
  "confidence": 0.0,
  "reason": "string",
  "evidence": { ... },
  "retry_guidance": { ... }
}

Evidence contains PoI/PoUW outputs, consensus stats, reputation view, and/or schema failures. (Cortensor)

---

3) GAME Function API

3.1 delegate_to_corgent

Use case: Delegation-as-a-Service. Pattern: GAME Worker → Corgent → Cortensor → Corgent → Worker.

Signature (conceptual):

def delegate_to_corgent(task: Task, policy: Policy) -> DelegationResponse

Request

{
  "task": {
    "task_id": "uuid",
    "type": "inference",
    "input": {
      "prompt": "Summarize X",
      "params": { "max_tokens": 256 }
    },
    "spec": null
  },
  "policy": {
    "policy": "safe",
    "redundancy": 3,
    "model_pref": "auto",
    "sla_tier": "high_reliability"
  },
  "payment": {
    "mode": "stake_to_use | pay_per_use | x402",
    "budget_cor": 25,
    "x402_invoice_id": null
  }
}

Response

{
  "task_id": "uuid",
  "output": "...final chosen output...",
  "confidence": 0.86,
  "evidence": {
    "miners_used": 3,
    "poi_cluster": { "k": 2, "similarity": 0.91 },
    "pouw_score": 0.82,
    "reputation_weighting": { "minerA": 0.41, "minerB": 0.34, "minerC": 0.25 },
    "integrity_checks": "pass"
  },
  "verdict": "VALID",
  "cost": { "cor_spent": 7.2, "gas_spent": "auto" }
}

Notes:

• payment.mode aligns with Cortensor’s Pay-Per-Use + Stake-to-Use rails; Router-level x402 is planned in agentic phases. (Cortensor)

---

3.2 validate_with_corgent

Use case: Validation-as-a-Service (Result Oracle).

Signature (conceptual):

def validate_with_corgent(task: Task, claimed_result: Any, policy: Policy) -> ValidationResponse

Request

{
  "task": {
    "task_id": "uuid",
    "type": "validation",
    "input": {
      "prompt": "Write 5 bullets on competitors",
      "params": {}
    },
    "claimed_result": {
      "output": ["...seller bullets..."],
      "metadata": { "agent_id": "seller123" }
    },
    "spec": {
      "constraints": { "max_bullets": 5 }
    }
  },
  "policy": {
    "policy": "safe",
    "redundancy": 3,
    "min_confidence": 0.8
  }
}

Response

{
  "task_id": "uuid",
  "verdict": {
    "status": "RETRY",
    "confidence": 0.79,
    "reason": "Consensus outlier vs PoI cluster",
    "evidence": {
      "poi_cluster_similarity": 0.88,
      "seller_alignment": 0.52,
      "pouw_score_cluster": 0.81
    },
    "retry_guidance": {
      "instruction": "Include competitors A/B/C, <=5 bullets, cite sources."
    }
  }
}

---

3.3 arbitrate_with_corgent

Use case: Arbitration-as-a-Service (Buyer/Seller dispute).

Signature (conceptual):

def arbitrate_with_corgent(task: Task, claimed_result: Any, policy: Policy) -> ArbitrationResponse

Request

{
  "task": {
    "task_id": "uuid",
    "type": "arbitration",
    "input": { "prompt": "Generate 10 product names w/ constraints", "params": {} },
    "claimed_result": { "output": ["...seller output..."] },
    "spec": { "constraints": { "must_include": ["X","Y"], "count": 10 } }
  },
  "policy": {
    "policy": "oracle",
    "redundancy": 5,
    "min_confidence": 0.9
  }
}

Response

{
  "task_id": "uuid",
  "binding_verdict": {
    "status": "INVALID",
    "confidence": 0.93,
    "reason": "Spec violation confirmed by oracle-grade consensus",
    "evidence": {
      "miners_used": 5,
      "poi_consensus": "stable",
      "pouw_score": 0.87,
      "spec_failures": ["missing X", "count != 10"]
    }
  },
  "settlement_hint": {
    "action": "refund_buyer",
    "percent": 100
  }
}

---

4) ACP Surface (Marketplace)

4.1 ACP Job Template

When listed as an ACP Seller/Evaluator, Corgent advertises:

{
  "service_id": "corgent.validate.v1",
  "role": "evaluator",
  "capabilities": ["delegation", "validation", "arbitration"],
  "pricing": {
    "mode": "x402",
    "base_per_call_cor": 1.0,
    "tiers": { "fast": 1, "safe": 3, "oracle": 5 }
  },
  "metadata": {
    "erc8004_validation_artifacts": true,
    "supports_poi": true,
    "supports_pouw": true
  }
}

ERC-8004 artifacts/identity are part of Cortensor’s agentic alignment. (Cortensor)

4.2 ACP Calls

• Buyer → Corgent (validate/arbitrate)

• Seller → Corgent (optional pre-verify)

• Corgent returns verdict used for settlement

Field shapes match the GAME API above, plus ACP job ids:

{
  "job_id": "acp_uuid",
  "buyer_agent_id": "buyer123",
  "seller_agent_id": "seller456",
  "task": { ... },
  "policy": { ... }
}

---

5) Evidence Object (Common)

{
  "miners_used": 3,
  "redundancy": 3,
  "poi": {
    "method": "embedding_distance",
    "cluster_k": 2,
    "similarity_mean": 0.91,
    "outliers": ["minerC"]
  },
  "pouw": {
    "verifier_model": "validator_v3",
    "score_mean": 0.82,
    "score_breakdown": { "usefulness": 0.85, "coherence": 0.79 }
  },
  "reputation": {
    "weights": { "minerA": 0.41, "minerB": 0.34, "minerC": 0.25 }
  },
  "integrity": {
    "commit_reveal": "pass",
    "session_root": "0x..."
  },
  "artifacts": {
    "attestation_jws": "base64...",
    "erc8004_validation_ref": "0x..."
  }
}

Attestation + ERC-8004 validation registry linkage is explicitly in the agentic Testnet plan. (Cortensor)

---

6) Error Codes

{
  "error": {
    "code": "NEEDS_SPEC | BUDGET_EXCEEDED | ROUTER_UNAVAILABLE | LOW_CONFIDENCE | SCHEMA_FAIL",
    "message": "human readable"
  }
}

• NEEDS_SPEC used when task is underspecified or schema missing (per your design).

• LOW_CONFIDENCE triggers adaptive escalation if enabled.

---

7) Payments & Auth (Draft)

Corgent supports three payment modes:

1. Stake-to-Use: uses caller’s staked COR session budget

2. Pay-Per-Use: spends COR from prepaid balance

3. x402: per-call invoice settlement at Router/Corgent surface

x402 at Router/Agent level is the current intended direction; core-level x402 remains optional. (Cortensor)

Auth:

• Virtual SDK agents authenticate via standard GAME/Virtual keys. (GitHub)

• Corgent authenticates to Cortensor Router Nodes using session auth + on-chain identity (exact scheme finalized during agentic phases). (Cortensor)

---

8) Versioning

• corgent.*.v1 indicates stable GAME/ACP callable surfaces.

• Breaking changes bump major (v2).

• Evidence schema additions are backward-compatible.

---

9) Minimal Usage Examples

Delegation

result = delegate_to_corgent(
  task={"input":{"prompt":"Summarize X"}},
  policy={"policy":"safe","redundancy":3}
)

Validation

verdict = validate_with_corgent(
  task={"input":{"prompt":"Write 5 bullets"}},
  claimed_result=seller_output,
  policy={"policy":"safe","redundancy":3}
)

Arbitration (ACP)

binding = arbitrate_with_corgent(
  task=acp_job.task,
  claimed_result=acp_job.seller_output,
  policy={"policy":"oracle","redundancy":5}
)

---

What I couldn’t confirm from public docs

Public Cortensor docs don’t yet publish the final Router /completions or /validate wire schema nor the final Virtual ACP function naming. So the endpoint names and some field titles above are drafted to match your concept + the published agentic roadmap, and should be treated as spec-level placeholders until Testnet Phase 3–4 SDKs finalize. (Cortensor)