# \[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](https://docs.cortensor.network/technical-architecture/node-lifecycle?utm_source=chatgpt.com))

***

### 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](https://github.com/Virtual-Protocol/virtuals-python?utm_source=chatgpt.com))

#### 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](https://whitepaper.virtuals.io/acp-product-resources/acp-concepts-terminologies-and-architecture?utm_source=chatgpt.com))

***

### 2) Core Concepts

#### 2.1 Task

A unit of work to run or verify.

```json
{
  "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

```json
{
  "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](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

#### 2.3 Verdict

```json
{
  "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](https://docs.cortensor.network/technical-architecture/node-lifecycle?utm_source=chatgpt.com))

***

### 3) GAME Function API

#### 3.1 `delegate_to_corgent`

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

**Signature (conceptual):**

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

**Request**

```json
{
  "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**

```json
{
  "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](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

#### 3.2 `validate_with_corgent`

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

**Signature (conceptual):**

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

**Request**

```json
{
  "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**

```json
{
  "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):**

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

**Request**

```json
{
  "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**

```json
{
  "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:

```json
{
  "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](https://docs.cortensor.network/technical-architecture/designs-wip/agentic-wip-draft/erc-8004-in-context-from-trust-fabric-to-execution-fabric-draft?utm_source=chatgpt.com))

#### 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:

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

***

### 5) Evidence Object (Common)

```json
{
  "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](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

### 6) Error Codes

```json
{
  "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](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

Auth:

* Virtual SDK agents authenticate via standard GAME/Virtual keys. ([GitHub](https://github.com/Virtual-Protocol/virtuals-python?utm_source=chatgpt.com))
* Corgent authenticates to Cortensor Router Nodes using session auth + on-chain identity (exact scheme finalized during agentic phases). ([Cortensor](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))

***

### 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

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

#### Validation

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

#### Arbitration (ACP)

```python
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](https://docs.cortensor.network/community-and-ecosystem/community-testing/testnet-phase/testnet-phases-and-focus-areas-structured-plan?utm_source=chatgpt.com))


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortensor.network/technical-architecture/designs-wip/corgent-overview-virtual-trust-oracle-on-cortensor/wip-corgent-api-spec-draft-v0.1.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.