Quickstart — Kepler in 30 seconds¶

The bundled example is not a toy. It queries the NASA Exoplanet Archive for every confirmed planet with a measured orbital period and semi-major axis, and recovers Kepler's Third Law from those measurements alone.

It needs no API key, no account and no local dataset.

1. Scaffold and run¶

science-adk init my-kepler --example kepler
cd my-kepler
science-adk run

fetch:    fetched 3565 confirmed exoplanets from NASA
analyze:  fit 3565 planets: T ∝ a^1.4555, r² = 0.989997
evaluate: recovered exponent 1.4555 vs theoretical 1.5000, error 0.0445

Exact numbers move as the archive grows — that is the point. Nothing is cached, and nothing is hard-coded.

2. What ran¶

science-adk graph

graph LR
    config["config<br/><i>config</i>"] -->|settings| fetch["fetch<br/><i>data</i>"]
    config -->|settings| evaluate["evaluate<br/><i>evaluation</i>"]
    fetch -->|planets| analyze["analyze<br/><i>algorithm</i>"]
    analyze -->|fit_result| evaluate

Four nodes, four typed edges, defined in research/001-kepler-exoplanets/workflow.json:

Node	Kind	Does	Declares tools
`config`	`config`	Emits query filters and the theoretical exponent.	—
`fetch`	`data`	Queries NASA's public TAP endpoint.	`query_exoplanets`
`analyze`	`algorithm`	Fits `T = C·aᵅ` in log-log space.	`power_law_fit`
`evaluate`	`evaluation`	Compares the recovered exponent against 3/2.	—

Each node has exactly one Python file in agents/, and the edges carry named, typed ports — config.settings → fetch.settings, fetch.planets → analyze.planets, and so on.

3. Check the gates¶

science-adk score

  [pass] execution_completed: All nodes ran to completion.
  [pass] all_nodes_ran: 4 node(s) produced output.
  [pass] result_measured: evaluate reported a measurement.
  [pass] metric_is_finite: evaluate reported 0.989997.
  [pass] produced_output: 6 output value(s) recorded.
  [pass] tool_use_verified: Declared tool use matches the record.

These are not stylistic checks. They are machine-verified conditions computed from the recorded trace, and any failure scores the run 0.00. See integrity gates.

A green run is not yet a finding

score reports 0.00 until a human (or an agent acting under the auditing skill) records a verdict with science-adk audit. Passing the gates only proves the number is real — not that it is interesting.

4. Read the result¶

science-adk report
cat research/001-kepler-exoplanets/runs/*/REPORT.md

Every run directory holds a complete trace.json: each node's inputs, outputs, logs, timings, fingerprint and the provenance ledger of every tool call it made.

jq '.nodes[] | {node_id, state, duration_s}' \
  research/001-kepler-exoplanets/runs/*/trace.json

5. Try to break it¶

The most instructive thing you can do is fabricate a result. Open research/001-kepler-exoplanets/agents/analyze.py, delete the call_tool line, and hard-code a perfect answer:

fit = {"exponent": 1.5, "coefficient": 1.0, "r_squared": 1.0, "n": len(periods)}

Then run and score again:

science-adk run
science-adk score

  [FAIL] tool_use_verified: Node(s) declared tools but made no successful
         tool call: analyze. Either the data was not really fetched, or the
         declaration is wrong.

Score: 0.00 — a failed gate means this run is not a result.

Every structural gate still passes. Only the provenance ledger — recorded by the runtime, not by the agent — knows the fit never happened. This exact scenario runs in CI on every push.

Why 1.4555 and not 1.5000¶

The ~3% shortfall is physics, not error. Kepler's constant goes as (4π²/GM)^½, so pooling planets across host stars of different masses pulls the fitted slope slightly below the single-star ideal. An experiment that returned exactly 1.5000 from a heterogeneous population would be the suspicious one.

Next¶

Understand the example fully

Every agent file, the tools, the trace, the fabrication test.

Kepler walkthrough
Start your own question

The same loop, applied to something you actually want to know.

Your first project