Documentation / API & CLI

A clear path
from question to evidence.

Explore OceanGraph’s CLI, hosted API, research workflows and reusable evidence resources.

Create an API token ↗Explore the project ↗

Overview

OceanGraph pairs a hosted knowledge graph of ocean-science literature, concepts, methods and events with a pip-installable CLI. This release keeps the original paper and news evidence search and its four report types, and adds a stateful research layer on top of them.

No model was retrained and no server-side vector store was replaced. The hosted API still performs online retrieval; the new local code handles routing, orchestration, state, source tracking, file analysis and delivery artifacts.

Research loop
natural-language question + optional local files
        -> Agent parses the goal and selects a Skill
        -> hosted API retrieves paper and news evidence
        -> local processing, validation and artifact generation
        -> Workspace persists multi-round state
        -> Resource exports a reusable bundle

Routing is deterministic by default. When an LLM is configured it is only called at steps with an explicit contract, and a network, model or evidence shortfall returns an explainable failure or uncertain state rather than invented evidence.

Runtime inputs

The CLI needs Python, plus a hosted API address and a personal token for online runs. Everything else is optional.

InputRequiredNotes
Python 3.9+YesRuns the CLI, the tests and the web workbench.
OCEANGRAPH_API_BASE_URLOnline onlyAddress of the hosted API.
OCEANGRAPH_API_KEYOnline onlyPersonal og_live_… token.
Natural-language questionYesFirst positional argument of oceangraph ask.
Local filesNoPDF, XML/TEI, JSON/JSONL, NetCDF/CDF, or a Resource.
OpenAI-compatible LLMNoOnly for synthesis, judgement and hypothesis tasks that need model reasoning.
Minimal environment
export OCEANGRAPH_API_BASE_URL="https://oceangraph.zjukg.cn"
export OCEANGRAPH_API_KEY="og_live_your_token_here"
export OCEANGRAPH_SOURCE="hosted"
export OCEANGRAPH_NETWORK_POLICY="online"
export OCEANGRAPH_RUNS_DIR="./runs"
export OCEANGRAPH_WORKSPACES_DIR="./workspaces"
export OCEANGRAPH_TIMEOUT=300
Optional model configuration
export OCEANGRAPH_LLM_BASE_URL="https://your-provider.example/v1"
export OCEANGRAPH_LLM_API_KEY="your_llm_api_key_here"
export OCEANGRAPH_LLM_MODEL="your-model-name"
export OCEANGRAPH_LLM_TIMEOUT=120

Real keys belong in environment variables or an uncommitted .env. scripts/oceangraph-local reads .env from the repository root automatically; a directly installed oceangraph expects the shell to export those variables first.

Create an API token

Use Quick Start to create a personal token. Enter your project details, verify your contact email, and copy the token into your client environment.

  1. Enter your name, organization, contact email and use case.
  2. Request a verification code and enter the code from your inbox.
  3. Create the token, copy the configuration and verify access.

A newly issued token is displayed in the creation response. Keep it in your client environment and outside source control.

Configure and verify access

Client credentials
export OCEANGRAPH_API_BASE_URL="https://oceangraph.zjukg.cn"
export OCEANGRAPH_API_KEY="og_live_your_token_here"
oceangraph auth status
Verify with the API
curl "$OCEANGRAPH_API_BASE_URL/api/auth/me" \
  -H "Authorization: Bearer $OCEANGRAPH_API_KEY"

Quick Start also accepts an existing token and can display its request count and remaining monthly quota.

Review and revoke tokens

Open the Manage step in Quick Start. Request a management code for the owner email, then load the issued tokens. Revoking an active token stops access for clients using that key.

MethodEndpointPurpose
POST/api/auth/send-codeRequest an email code. Use purpose api_token_management for management.
POST/api/auth/tokenCreate a token with verified project details.
GET/api/auth/meVerify a Bearer token.
GET/api/auth/usage?days=7Read token usage.
POST/api/auth/tokens/listList tokens after email verification.
POST/api/auth/tokens/revokeRevoke a token using its tokenId and verified owner email.

Install and first run

Clone, install, run
git clone https://github.com/OceanGPT/OceanGraph.git
cd OceanGraph
python -m venv .venv
source .venv/bin/activate
python -m pip install -e "./oceangraph[observations]"

cp .env.example .env
# edit .env and add your own OCEANGRAPH_API_KEY

./scripts/oceangraph-local health
./scripts/oceangraph-local auth status
./scripts/oceangraph-local ask \
  "Find the key evidence that marine heatwaves drive coral bleaching" \
  --workflow-mode standard \
  --max-requests 4

Once installed, every ./scripts/oceangraph-local invocation can be replaced with oceangraph.

Entry point and research loop

The recommended entry point is a single command:

Unified entry point
oceangraph ask "<research question>" [options]
OptionMeaning
--workflow-mode auto|flash|standard|fullLet the CLI decide, or set the workflow depth explicitly.
--max-requests NCap the hosted-API request budget for this round.
--workspace-id WS-...Attach a follow-up question to an existing Workspace.
--input PATHAdd a local input; repeatable.
--plan-onlyProduce the routing plan without running retrieval.
--resumeRestore the orchestration state saved in the Workspace.
--approve AP-...Approve a pending analysis checkpoint.
--jsonEmit a machine-readable result.
Run sequence
route -> plan -> retrieve -> normalize evidence -> task processing
      -> persist Workspace -> report / audit / resource

Supported tasks

The router selects a Skill from the request, so you normally do not need to remember Skill IDs.

Skill IDUse whenTypical artifacts
ocean-quick-evidenceAnswering a small, well-scoped evidence question quickly.A compact evidence set and a quick report.
ocean-literature-reviewSystematically mapping the research progress on one ocean-science question.Review Plan, Paper Map, Evidence Matrix, review.
ocean-event-investigatorInvestigating a named marine event, its timeline and its mechanism.Event, Timeline, Source Table, event report.
ocean-trend-reportSeparating literature trends, public signals and observed trends.Trend Layers, analysis and trend report.
ocean-claim-verifierChecking whether a scientific claim is supported by evidence.Verification plan, Claim-Evidence Matrix, Verdict.
ocean-research-gap-mapFinding evidence-sparse or unretrieved regions of the search space.Gap Map and views.
ocean-hypothesis-groundingChecking how a new idea overlaps with, and departs from, prior work.Idea Structure, Prior-Art Matrix, Grounding Summary.
ocean-hypothesis-generatorProposing testable hypotheses from the research graph and its gaps.Hypothesis Cards.
ocean-observation-plannerMatching a hypothesis to data and an observation plan.Observation Plan, variable mapping.
ocean-data-validationValidating a claim with an approved local data analysis.Analysis Plan, Result, Claim Relation.
Inspect routing
oceangraph --offline ask "Investigate the 2024 global coral bleaching event" --plan-only --json
oceangraph skill list
oceangraph skill route --request "Investigate the 2024 global coral bleaching event"

Multi-round research

The first ask creates and returns a WS-… id. Later questions reuse it:

Continue a research thread
oceangraph ask \
  "Now check counter-evidence after 2015 and the limits of that claim" \
  --workspace-id WS-... \
  --max-requests 2

oceangraph workspace show WS-...
oceangraph workspace audit WS-...

A Workspace stores the research goal, branches, past runs, evidence state, open questions, claims, claim-evidence links, research-graph nodes and edges, and audit events. A follow-up reads that state and produces an incremental plan — it does not simply paste the previous natural-language answer back into a prompt.

Workspace isolation

Each question space gets its own directory:

Workspace layout
workspaces/<workspace_id>/
  workspace.json
  evidence-ledger.json
  open-questions.json
  claims.jsonl
  claim-evidence-links.jsonl
  graph-nodes.jsonl
  graph-edges.jsonl
  queries.jsonl
  events.jsonl

Isolation rules:

  1. Only a Workspace id passed explicitly with --workspace-id is read or modified.
  2. Independent tasks use different Workspace ids and share no mutable state.
  3. Branches, evidence state, claim revisions and graph changes all record their source and events.
  4. runs/<run_id>/ keeps the raw artifacts of a single request; the Workspace only registers the runs relevant to the current study.
  5. An exported Resource is a self-contained directory covering only the selected Workspace and branch.

This isolation is at the application path and state level, not an operating-system sandbox. If local files hold sensitive data, configure file permissions, a container or a separate user in the deployment environment.

Local files, approvals and Resources

Local inputs, approvals and export
# a document enters the claim and research-graph flow
oceangraph --offline ask \
  "Extract the main claims and build the research graph" \
  --input paper.pdf

# NetCDF analysis plans first, then waits for approval
oceangraph --offline ask \
  "Validate this claim against the observations" \
  --input claim.json \
  --input observations.nc

# continue with the exact checkpoint id returned by the command
oceangraph ask \
  "Continue the approved analysis" \
  --workspace-id WS-... \
  --approve AP-...

# package for delivery
oceangraph resource export WS-... --output my-resource
oceangraph resource validate my-resource

Approval points stop local analysis from running before the user has confirmed the variables, scope and method.

Artifacts and reading order

A single retrieval keeps the original artifact set:

Run layout
runs/<run_id>/
  request.json
  response.json
  evidence.json
  metadata.json
  summary.md
  report-*.md

To take over a task, work through the state in this order:

  1. workspace show WS-... — confirm the goal, status, branches and related runs.
  2. workspace audit WS-... — review the execution and provenance record.
  3. evidence-ledger.json — inspect evidence that was kept, rejected or annotated.
  4. claims.jsonl and claim-evidence-links.jsonl — check the conclusions and how they relate to evidence.
  5. The matching runs/<run_id>/metadata.json, evidence.json and report-*.md — locate the input and output of a single round.

Web workbench and local HTTP API

Start the workbench
oceangraph web

It opens http://127.0.0.1:8765/. The main local routes are:

RoutePurpose
POST /api/askProduce a unified task plan.
POST /api/jobsSubmit a confirmed task.
GET /api/jobs/<job_id>Read a task status.
GET /api/workspaces/<workspace_id>Read a Workspace.
POST /api/uploadsUpload a local scientific file.

The web workbench and the CLI share one orchestration path. The server binds to 127.0.0.1 only; a non-loopback address requires an explicit --allow-remote.

Minimal reproduction and acceptance

Checks that need neither network access nor a real key:

Offline checks
python -m pip install -e "./oceangraph[test,observations]"
oceangraph --offline ask \
  "Investigate the 2024 global coral bleaching event" \
  --plan-only --json
python -m pytest oceangraph/tests -q

Online path:

Online checks
oceangraph health
oceangraph auth status
oceangraph ask "Find the key paper evidence for coral bleaching" --max-requests 1

Acceptance: the offline plan returns a valid Skill and Workspace policy; the test suite passes; online tasks return a Workspace id, a run id and readable evidence and report paths; and no artifact contains a plaintext token.

Code map and extension

File or directoryResponsibility
oceangraph/src/oceangraph/cli.pyEvery CLI argument and command entry.
orchestration.py, simple_mode.pyUnified agent planning, execution and resume.
skill_router.py, data/skills/Skill registry, routing rules and capability declarations.
workspace.py, claim_ledger.py, graph_ledger.pyMulti-round state, claims and the research graph.
retrieval.py, client.pyHosted API calls and retrieval.
resource_bundle.py, resource_schema.pyResource export and validation.
document_ingest.py, argo_adapter.py, grid_adapter.pyLocal paper and observation adapters.
web.py, web_*, web/The local web workbench.
schema/Contracts for every stable JSON artifact.
tests/Minimal reproducible fixtures and regression tests.

A new Skill needs at minimum a Skill manifest, routing vocabulary, an execution adapter, an artifact schema, CLI and unified-agent wiring, and tests covering the success, insufficient-evidence and failure states. Do not commit local runs, evaluation output, source snapshots or stage archives to the repository.

Known boundaries

  • Online retrieval quality and availability are bounded by the hosted API.
  • Without an LLM, retrieval, Workspaces, the research graph, deterministic reports and Resources still work; steps that depend on model judgement degrade or return an uncertain state.
  • The Workspace research graph is built from the documents, claims, evidence and analysis relations ingested during that study. It is never written back to the server-side global knowledge graph.
  • NetCDF analysis follows an explicit, approved deterministic plan; it is not automatic completion of arbitrary scientific computation.
  • --max-requests is a client-side request budget, not a server-side token or account quota.