Skip to content

science.toml

The project configuration file. Its presence marks the project root: every command searches upward from the current directory until it finds one.

[project]
name = "kepler-exoplanets"

[tools.local]
path = "./tools"

[run]
node_timeout_s = 120
max_optimize_iterations = 5

[project]

Key Type Default Meaning
name string "research" Project name, used in reports.

[tools.<name>]

Each [tools.*] table declares one tool provider. The table name becomes the provider prefix in qualified tool names (local.power_law_fit, pubchem.get_compound_by_name).

Three kinds, distinguished by which key is present:

[tools.local]
path = "./tools"
Key Type Meaning
path string Directory of .py files, relative to the project root.

Every public top-level function in every .py file becomes a tool. The docstring is the description and the type hints are the schema.

[tools.pubchem]
command = "uvx mcp-pubchem"
Key Type Meaning
command string Command line, split shell-style, launched as a subprocess. 
[tools.remote_compute]
url = "https://mcp.example.org/api"
token_env = "COMPUTE_API_TOKEN"
Key Type Meaning
url string Endpoint of the MCP server.
token_env string Name of an environment variable holding the bearer token.

Never put the secret in this file. If token_env is set and the variable is empty, the registry raises rather than proceeding unauthenticated.

Any number of providers may be declared, and none is required.

[run]

Key Type Default (template) Meaning
node_timeout_s integer 900 How long a single node may take before it is abandoned.
max_optimize_iterations integer 5 How many improvement attempts before the optimiser stops and reports honestly that the target was not reached.

The Kepler example lowers node_timeout_s to 120, because a query that takes two minutes has failed.

The template, in full

science-adk init writes this:

[project]
name = "research"

# ── Tools ────────────────────────────────────────────────────────────────────
# Agents call tools by name. Three kinds of provider, and none is required —
# a project with only local tools is complete, offline and dependency-free.

# Your own Python functions. Every public function in tools/*.py becomes a
# tool; its docstring is the description and its signature is the schema.
[tools.local]
path = "./tools"

# Any MCP server, launched as a subprocess.
# [tools.pubchem]
# command = "uvx mcp-pubchem"

# Any MCP server reachable over HTTP.
# [tools.remote]
# url = "https://example.org/mcp"
# token_env = "SCIENCE_ADK_TOOLS_TOKEN"   # read from the environment, never stored here

# ── Execution ────────────────────────────────────────────────────────────────
[run]
# How long a single node may take before it is abandoned.
node_timeout_s = 900

# How many improvement attempts before the optimizer stops and reports honestly
# that the target was not reached.
max_optimize_iterations = 5

Checking it

science-adk tools          # every provider that loaded, and its tools
science-adk status         # the project as the CLI sees it

A provider that fails to load warns rather than aborting:

warning: tool provider 'pubchem' unavailable: ...

See also