Documentation

Build with CascadeAnnote.

A complete reference for the API, configuration, and integration model. Everything is type-safe, public, and runnable from a single Next.js deployment.

Overview

What CascadeAnnote does

CascadeAnnote is a four-layer in-context-learning data annotation pipeline. Given a corpus of labeled examples and a new piece of text, it returns the most likely label, a calibrated confidence score, the exemplars that drove the decision, and a content-addressed receipt suitable for on-chain attestation.

The entire pipeline is implemented in TypeScript and runs inside a single Next.js deployment. There are no external service dependencies — every layer has a deterministic local implementation.

Quickstart

Annotate a single text

POST /api/annotate
Content-Type: application/json

{
  "text": "Best purchase I have made all year.",
  "candidates": ["positive","neutral","negative"]
}

Returns an annotation result with the label, confidence, vote breakdown, retrieved exemplars, trace, and storage receipt.

API reference

Endpoints

POST/api/annotate

core

Annotate a single text. Body: { text, candidates? }.

POST/api/annotate/batch

core

Annotate up to 50 texts in one call.

GET/api/pipeline/status

control

Returns corpus size, label set, and configured thresholds.

GET/api/pipeline/stats

telemetry

Aggregated metrics: average confidence, latency, fallback rate.

GET/api/results

telemetry

Returns recent annotation results (most recent first).

DELETE/api/results

telemetry

Clears the in-memory result history.

GET/api/datasets

data

List active and uploaded corpora.

POST/api/datasets

data

Upload a corpus and (optionally) activate it as the live retriever.

GET/api/storage

List storage receipts for every persisted annotation.

POST/api/storage

Manually upload an arbitrary JSON payload to 0G Storage.

GET/api/agent

Returns the deployment’s agent DID, public key, and reputation.

GET/api/health

ops

Health probe with version, uptime, and 0G connectivity.

Configuration

Environment variables

Every variable is optional. Missing values fall back to deterministic local behavior, so you can run the entire app with zero secrets.

Key	Purpose
NEXT_PUBLIC_OG_NETWORK	Target network for the explorer link (mainnet \| testnet \| local).
OG_RPC_URL	0G Chain JSON-RPC endpoint. Required for live attestation.
OG_INDEXER_URL	0G Storage indexer URL. Required for real uploads.
OG_PRIVATE_KEY	Signer for storage uploads. Optional — anonymous mode is allowed.
OG_CONTRACT_ADDRESS	Annotation registry contract used to anchor receipts.
OG_AGENT_ID	Override the auto-derived agent DID.
INFERENCE_PROVIDER	openai \| og-compute. Empty = built-in local classifier.
OPENAI_API_KEY	Used only when INFERENCE_PROVIDER=openai.
ANNOTATION_TOP_K	Number of retrieved exemplars (default 5).
ANNOTATION_VOTE_RUNS	Self-consistency runs (default 5).
ANNOTATION_FALLBACK_THRESHOLD	Confidence below which fallback engages (default 0.6).

Deployment

Deploy to Vercel

Push the repository to GitHub, import it into Vercel, and ship. No additional services required.

# 1. Push to GitHub
git init && git add . && git commit -m "feat: cascadeannote v1"
git remote add origin git@github.com:<you>/cascadeannote.git
git push -u origin main

# 2. Import on Vercel
#    - Framework preset: Next.js (auto-detected)
#    - Build command:    next build
#    - Output:           .next
#    - (Optional) add the env vars from .env.example

Architecture deep-dive