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.
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 bundleRouting 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.
| Input | Required | Notes |
|---|---|---|
| Python 3.9+ | Yes | Runs the CLI, the tests and the web workbench. |
| OCEANGRAPH_API_BASE_URL | Online only | Address of the hosted API. |
| OCEANGRAPH_API_KEY | Online only | Personal og_live_… token. |
| Natural-language question | Yes | First positional argument of oceangraph ask. |
| Local files | No | PDF, XML/TEI, JSON/JSONL, NetCDF/CDF, or a Resource. |
| OpenAI-compatible LLM | No | Only for synthesis, judgement and hypothesis tasks that need model reasoning. |
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=300export 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=120Real 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.
- Enter your name, organization, contact email and use case.
- Request a verification code and enter the code from your inbox.
- 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
export OCEANGRAPH_API_BASE_URL="https://oceangraph.zjukg.cn"
export OCEANGRAPH_API_KEY="og_live_your_token_here"
oceangraph auth statuscurl "$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.
| Method | Endpoint | Purpose |
|---|---|---|
| POST | /api/auth/send-code | Request an email code. Use purpose api_token_management for management. |
| POST | /api/auth/token | Create a token with verified project details. |
| GET | /api/auth/me | Verify a Bearer token. |
| GET | /api/auth/usage?days=7 | Read token usage. |
| POST | /api/auth/tokens/list | List tokens after email verification. |
| POST | /api/auth/tokens/revoke | Revoke a token using its tokenId and verified owner email. |
Install and first 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 4Once installed, every ./scripts/oceangraph-local invocation can be replaced with oceangraph.
Entry point and research loop
The recommended entry point is a single command:
oceangraph ask "<research question>" [options]| Option | Meaning |
|---|---|
| --workflow-mode auto|flash|standard|full | Let the CLI decide, or set the workflow depth explicitly. |
| --max-requests N | Cap the hosted-API request budget for this round. |
| --workspace-id WS-... | Attach a follow-up question to an existing Workspace. |
| --input PATH | Add a local input; repeatable. |
| --plan-only | Produce the routing plan without running retrieval. |
| --resume | Restore the orchestration state saved in the Workspace. |
| --approve AP-... | Approve a pending analysis checkpoint. |
| --json | Emit a machine-readable result. |
route -> plan -> retrieve -> normalize evidence -> task processing
-> persist Workspace -> report / audit / resourceSupported tasks
The router selects a Skill from the request, so you normally do not need to remember Skill IDs.
| Skill ID | Use when | Typical artifacts |
|---|---|---|
| ocean-quick-evidence | Answering a small, well-scoped evidence question quickly. | A compact evidence set and a quick report. |
| ocean-literature-review | Systematically mapping the research progress on one ocean-science question. | Review Plan, Paper Map, Evidence Matrix, review. |
| ocean-event-investigator | Investigating a named marine event, its timeline and its mechanism. | Event, Timeline, Source Table, event report. |
| ocean-trend-report | Separating literature trends, public signals and observed trends. | Trend Layers, analysis and trend report. |
| ocean-claim-verifier | Checking whether a scientific claim is supported by evidence. | Verification plan, Claim-Evidence Matrix, Verdict. |
| ocean-research-gap-map | Finding evidence-sparse or unretrieved regions of the search space. | Gap Map and views. |
| ocean-hypothesis-grounding | Checking how a new idea overlaps with, and departs from, prior work. | Idea Structure, Prior-Art Matrix, Grounding Summary. |
| ocean-hypothesis-generator | Proposing testable hypotheses from the research graph and its gaps. | Hypothesis Cards. |
| ocean-observation-planner | Matching a hypothesis to data and an observation plan. | Observation Plan, variable mapping. |
| ocean-data-validation | Validating a claim with an approved local data analysis. | Analysis Plan, Result, Claim Relation. |
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:
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:
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.jsonlIsolation rules:
- Only a Workspace id passed explicitly with
--workspace-idis read or modified. - Independent tasks use different Workspace ids and share no mutable state.
- Branches, evidence state, claim revisions and graph changes all record their source and events.
runs/<run_id>/keeps the raw artifacts of a single request; the Workspace only registers the runs relevant to the current study.- 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
# 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-resourceApproval 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:
runs/<run_id>/
request.json
response.json
evidence.json
metadata.json
summary.md
report-*.mdTo take over a task, work through the state in this order:
workspace show WS-...— confirm the goal, status, branches and related runs.workspace audit WS-...— review the execution and provenance record.evidence-ledger.json— inspect evidence that was kept, rejected or annotated.claims.jsonlandclaim-evidence-links.jsonl— check the conclusions and how they relate to evidence.- The matching
runs/<run_id>/metadata.json,evidence.jsonandreport-*.md— locate the input and output of a single round.
Web workbench and local HTTP API
oceangraph webIt opens http://127.0.0.1:8765/. The main local routes are:
| Route | Purpose |
|---|---|
| POST /api/ask | Produce a unified task plan. |
| POST /api/jobs | Submit a confirmed task. |
| GET /api/jobs/<job_id> | Read a task status. |
| GET /api/workspaces/<workspace_id> | Read a Workspace. |
| POST /api/uploads | Upload 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:
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 -qOnline path:
oceangraph health
oceangraph auth status
oceangraph ask "Find the key paper evidence for coral bleaching" --max-requests 1Acceptance: 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 directory | Responsibility |
|---|---|
| oceangraph/src/oceangraph/cli.py | Every CLI argument and command entry. |
| orchestration.py, simple_mode.py | Unified agent planning, execution and resume. |
| skill_router.py, data/skills/ | Skill registry, routing rules and capability declarations. |
| workspace.py, claim_ledger.py, graph_ledger.py | Multi-round state, claims and the research graph. |
| retrieval.py, client.py | Hosted API calls and retrieval. |
| resource_bundle.py, resource_schema.py | Resource export and validation. |
| document_ingest.py, argo_adapter.py, grid_adapter.py | Local 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-requestsis a client-side request budget, not a server-side token or account quota.
No matching sections. Try a shorter search.