Learned Tool API

The /api/v1/tools API stores immutable artifacts, registers external executor profiles and records development/repair outcomes. A client can use ordinary HTTPS JSON requests without a compiler, model or local execution runtime. The database stores source and evidence; separately deployed workers generate and test code. These routes do not dispatch programs or publish executable releases.

Use http://localhost:7474 for local Docker. The interactive reference is /docs; OpenAPI describes every request and response. Requests require contract_version: 1, reject unknown fields and share the 65536-byte transport limit. Successful commands and reads return 200, including non-successful worker outcomes. Check the returned state and reason, not only HTTP status. Responses carry Cache-Control: no-store.

Ownership and compatibility#

These existing routes document artifact and development records; they do not assign ownership of tool code or execution to QilbeeDB. Applications retain that responsibility. New knowledge integrations should follow the external tool knowledge boundary, without requiring code or executor registration. No endpoint removal or data migration is introduced by this clarification.

Credentials and routes#

Use Authorization: Bearer <credential>. The credential administrator issues separate credentials with explicit capabilities. Existing memory or procedural capabilities do not grant tool access. Bootstrap administrators can issue a tool_admin credential; bootstrap does not implicitly include that capability. Tenant and actor are derived from current credentials, never from request JSON.

Endpoint Capability and additional authority Response
POST /api/v1/tools/executors tool_admin executor
GET /api/v1/tools/executors/{id} tool_admin executor
POST /api/v1/tools/artifacts tool_develop, exact scope artifact
POST /api/v1/tools/artifacts/read tool_read, exact scope artifact
POST /api/v1/tools/development/requests tool_develop, exact scope original receipt
POST /api/v1/tools/development/read tool_read, exact scope current development
POST /api/v1/tools/development/commands with report tool_report, exact scope, registered executor subject original event
Same endpoint with request_cancellation tool_develop, exact scope, original requesting subject original event
POST /api/v1/tools/development/events/read tool_read, exact scope original event

Each response is an envelope with contract_version: 1 and the named field. Shared access requires the same exact grant in the same tenant. Private scope includes the authenticated subject, so a separate worker subject cannot report on another subject's private request. Use a shared scope with explicit grants for separate developer/worker identities. Revoked, rotated-old or expired secrets cannot authorize a later request. An operation already authorized may finish while revocation races with it.

Register an executor and request development#

An administrator posts this synthetic profile to /api/v1/tools/executors:

{
  "contract_version": 1,
  "profile": {
    "id": "worker-v1",
    "subject_id": "worker",
    "runtime_image_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "environment_revision": "sandbox-v1",
    "permissions_revision": "no-network-v1",
    "max_cost_units": 100,
    "max_latency_ms": 60000
  }
}

Use a real immutable image digest in integration. Preserve the returned executor.profile_digest. Profile IDs are immutable within the tenant; changed content requires a new ID. Profiles contain no endpoints or worker passwords. They declare expected authority and execution context, not a sandbox attestation. Cost units must have a consistent deployment-defined meaning.

A developer posts this to /api/v1/tools/development/requests:

{
  "contract_version": 1,
  "scope": {"project_id":"project","mission_id":null,"agent_id":"agent","visibility":"shared"},
  "request": {
    "id": "request-v1",
    "executor_id": "worker-v1",
    "objective": "Develop an identity tool and run its tests.",
    "parent_artifact_id": null,
    "repair_evidence_ref": null
  }
}

The receipt preserves the immutable request, request digest, executor profile digest, tenant/namespace, requesting actor and timestamp. Repeating the same request ID/content by the same subject returns the original receipt, even after completion. Changed content or a different requester conflicts. For a repair, both parent and evidence are required; the parent must exist in the same scope. External evidence references are preserved as declarations, without fetching them.

Creation records intent. It does not dispatch work. A configured worker is given the request ID and shared scope and reads the current state at /api/v1/tools/development/read:

{
  "contract_version": 1,
  "scope": {"project_id":"project","mission_id":null,"agent_id":"agent","visibility":"shared"},
  "request_id": "request-v1"
}

Report a candidate or failure#

Post to /api/v1/tools/development/commands with the worker credential. Replace the zero-filled digest with the exact registered executor_profile_digest:

{
  "contract_version": 1,
  "scope": {"project_id":"project","mission_id":null,"agent_id":"agent","visibility":"shared"},
  "request_id": "request-v1",
  "command": {
    "event_id": "tests-completed-v1",
    "expected_revision": 1,
    "action": {
      "type": "report",
      "report": {
        "executor_profile_digest": "0000000000000000000000000000000000000000000000000000000000000000",
        "outcome": "succeeded",
        "evidence_ref": "test-run-v1",
        "detail": "Identity cases passed in the configured worker.",
        "cost_units": 10,
        "latency_ms": 100,
        "artifact": {
          "id": "identity-v1",
          "source": "def run(value):\n    return value\n",
          "dependency_lock": "",
          "runtime_image_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
          "entrypoint": "tool:run",
          "input_schema": true,
          "output_schema": true,
          "source_refs": ["development:request-v1"],
          "parent_artifact_id": null,
          "repair_evidence_ref": null
        }
      }
    }
  }
}

This is a payload example, not measured tool efficacy. Successful reports must match the bound runtime image, parent/evidence and development:<request ID> source reference. The artifact and resulting state are committed atomically with the event. Changed event retries conflict; identical retries return the original event snapshot and actor. Credential rotation is compatible when subject and grants stay the same. New commands require the latest revision.

For a failed or pending report, use outcome failed or pending_or_unknown, set artifact to null, and preserve a diagnostic evidence_ref/detail. Unknown accounting is null. A reported success with unknown accounting remains pending; a known budget violation becomes failure. Known cumulative accounting cannot decrease, including across unknown reports. observed_cost_units and observed_latency_ms retain known lower bounds while current consumption may be unknown. See the complete state contract.

Cancellation and immutable event reads#

The original requester can ask to cancel a nonterminal request:

{
  "contract_version": 1,
  "scope": {"project_id":"project","mission_id":null,"agent_id":"agent","visibility":"shared"},
  "request_id": "request-v1",
  "command": {
    "event_id": "cancel-v1",
    "expected_revision": 1,
    "action": {"type":"request_cancellation","reason":"The mission ended."}
  }
}

State becomes cancellation_requested. Only a bound worker report with outcome cancelled confirms cancellation. A complete success can win the race before that confirmation. New commands after a terminal state conflict; old identical receipts remain replayable. No automatic redispatch occurs on timeout or restart.

Read an original receipt at /api/v1/tools/development/events/read:

{
  "contract_version": 1,
  "scope": {"project_id":"project","mission_id":null,"agent_id":"agent","visibility":"shared"},
  "request_id": "request-v1",
  "event_id": "cancel-v1"
}

Direct artifacts and response fields#

To import source without claiming development success, post {contract_version, scope, artifact} to /api/v1/tools/artifacts, using the same artifact shape as the worker example. Read it with {contract_version, scope, artifact_id} at /api/v1/tools/artifacts/read.

Artifacts retain proposal, artifact_digest, exact source/dependency SHA-256 digests, actor, timestamp, tenant, namespace and schema version. Executor records retain profile, profile_digest and administrative provenance. Development state retains its original receipt, revision, state, reason, last_event_id, optional exact artifact ID/digest and nullable accounting. Events retain the complete command, reporting actor, resulting record, schema version and timestamp. An old event's snapshot may differ from current state; read the development record for the latest state.

The artifact contract lists byte limits and digest semantics. Objectives/details support 8192 bytes; evidence and cancellation reasons support 2048 bytes. Schemas are stored declarations, not compiled validators. Source, lock files and evidence must contain no credentials. A successful artifact is not automatically published or authorized for invocation.

Errors#

Status/code Meaning
400 invalid_request Unknown fields/version, invalid bounds or malformed report
401 unauthorized Invalid, expired, revoked or replaced bearer secret
403 forbidden Missing capability/grant or wrong requesting/executor subject
404 record_not_found Request, artifact, event or executor absent in authorized scope/tenant
409 revision_conflict A new command used a stale revision
409 idempotency_conflict Changed immutable content, mismatched runtime/provenance/profile, or invalid terminal transition
413 invalid_request Complete request body exceeds 65536 bytes
500 storage_inconsistency Stored identity, digest, state/event or artifact mismatch

Errors use {contract_version, error: {code, message}}. On an ambiguous transport failure, replay the identical request/event ID. Do not invent a new operation ID that could cause duplicate external work. The database's receipts coordinate worker evidence; workers still need their own durable execution identities, isolation and reconciliation protocol.