huang-sh/deepscience/biological-knowledge

Biological Knowledge

Route first, query second. Select sources by entity type, organism, identifier namespace, evidence model, and release. The resource tool progressively exposes database metadata and instructions; the Agent determines the task-specific execution from each loaded package.

Workflow

1. Record the requested entity, organism, namespace, evidence type, freshness requirement, and any

named database. A named database selects that source; an unnamed database-dependent set request selects every scientifically applicable package returning the requested entity type. This step is complete when the source inclusion and exclusion rules are explicit.

1. Browse the relevant domain with `resource({ action: "list", category:

"<selected-category-path>" }). When the response has kind: "categories", choose an exact child path and list it; repeat until the response has kind: "resource_metadata". Category entries are navigation choices, while resource_metadata` entries are selectable packages.

This step is complete when every branch matching the inclusion rules from step 1 has reached resource_metadata and every returned candidate has been compared by scientific scope, organism, entity type, and access mode.

1. Load only the selected package instructions using the exact name copied from its leaf

metadata:

resource({ action: "read", name: "<exact-resource-name>" })

Treat the loaded RESOURCE.md as the authoritative access contract. Follow its reference routing before data access: read the named schema or interpretation reference when the requested result depends on entity filtering, member counting, identifier mapping, pagination, or endpoint semantics. Inspect a bundled script's --help or source only when the package documentation does not state the required invocation. Use the loaded package contract as the source of database-specific access instructions.

This step is complete when each selected package's query interface, response schema, identifier semantics, version behavior, required references, and path conventions are known well enough to define the intended result before querying.

1. Build a retrieval ledger with one row per selected package: exact package name, discovery

operation when an ID is unknown, complete retrieval operation, documented output schema, and intended raw artifact. Execute each package according to its loaded access contract. Use live services for remote and bundled snapshots for local.

For hybrid, apply the package's local coverage gate before any network call. Local coverage is sufficient only when the available data—not merely documentation or a client script—matches the requested operation, entity, organism, identifier namespace, release requirement, and complete membership or fields. Use that local result alone when the gate passes. Escalate only the uncovered request to the documented remote service when the gate fails, the local result is a valid empty result, or the user requires current/live data or independent remote validation. Record the gate decision and fallback reason; keep local and remote evidence separate when both were explicitly required.

Give each selected record one complete retrieval. Use a separate discovery request only when the exact record ID is unknown. Prefer a package's structured output option and treat its documented schema as the contract. Let one workspace consolidation script be the first consumer of completed raw outputs: read every selected output once, perform task-specific filtering and mapping, and write all derived source artifacts and provenance in one run. Then validate all output schemas, array lengths, hashes, and reported counts in one pass. Additional inspection is reserved for a failed documented-schema check, changed parameters, pagination, recovery, or an independent validation request.

This step is complete when every ledger row has one result, a valid empty result, or a concrete failure, and every successful row points to its raw and derived artifacts.

1. Pass the runtime Artifact report gate. Preserve complete results in canonical workspace

artifacts, then report every source independently with its database, query or record, organism, namespace, release or retrieval date, access mode, exact result count, and artifact path. Perform merging or identifier mapping only when requested.

This step is complete when all selected sources and returned members are accounted for in the artifacts; every reported identifier is present in a documented artifact field; every reported count is computed from an artifact field; and complete membership lists remain in deterministic artifacts rather than model-composed prose.

Interpret an empty response as version-specific evidence. Use package directories as read-only sources and write all generated output to the Session workspace.