fredv0.3.0

What fred is

The loop, and where it sits.

fred is a research assistant service that answers a scientific question by looking things up rather than by recalling them. It works as a loop run by a language model: it reasons about what to check next (Thought), calls one public database (Action: UniProt, PubChem, PubMed, Open Targets, Reactome, or a web search), reads the result (Observation), and goes round again until it decides it can answer or its step budget is spent.

Applications such as Compound Insights and SIM send fred a question and receive an answer with a record of every lookup. fred is a component inside them, not a standalone tool.

Ten tools are registered and all ten are offered on every turn. One language model backend is configured: kimi-k2.6:cloud, reached through a local Ollama daemon. The step budget defaults to 30 turns and the caller can set it between 1 and 200.

What v0.3.0 adds: provenance

Seeing, after the fact, exactly what fred did to reach an answer.

• Every database call is recorded. For each lookup: which database, what was asked, when, how long it took, whether it succeeded, and a fingerprint (hash) and size of what came back. An answer can now be audited.
• Failures are honest. Every lookup reports one of three outcomes: found, found nothing, or failed. A failure says why: server down, unexpected reply, bad input, or missing configuration.
• Live progress. While a question is in progress, the application can see how many steps and lookups have happened.
• The step budget works. An application can cap how many reasoning steps fred takes, and fred honors the cap.
• One question at a time, by design. fred says when it is busy rather than queueing silently.

What you get back

The status record, and the eleven fields kept for every tool call.

A completed run returns the model's final text as final_response, together with tool_calls: one record per tool call, in call order, complete. That list is the provenance record and the reason this release exists.

Eleven fields per tool call

The complete body is not retained anywhere. Only its length and its hash survive. Recovering the full result of a lookup means asking the database the same question again.

The outcome vocabulary

Every tool body is one JSON object whose first key is outcome, with three possible values: OK, EMPTY (an authority answered "nothing"), and ERROR. An error body also carries an error_class, one of twelve: NO_RESPONSE, UPSTREAM_STATUS, UNEXPECTED_CONTENT_TYPE, UNPARSEABLE_BODY, UNEXPECTED_SHAPE, UPSTREAM_REPORTED_ERROR, INVALID_ARGUMENT, NOT_CONFIGURED, PATH_UNRESOLVABLE, WORKSPACE_REFUSED, TARGET_NOT_FOUND, TARGET_UNUSABLE.

is_error is two-valued and the vocabulary is three-valued: found-nothing is not an error, and the flag does not say found-nothing. Read outcome to tell "found nothing" from "found".

Key fields on the status record

A failed run carries its tool call count but no list of tool call records: the calls were made, and their records are not on the wire.

How it was tested

Three real questions, asked of the deployed service, checked four ways.

fred's own test set runs 936 tests, all passing. Every database tool has tests that a failing server, a timeout, or a malformed reply is reported as a failure. Those tests exercise the code; they say nothing about whether an answer is right. That is what the golden test suite is for.

The three questions

Each question was chosen so that a correct answer is a small set of specific values that a database holds today, and so that a wrong answer is unambiguous rather than a matter of opinion. Each is asked three times, because fred is not deterministic and one run proves nothing.

The expected answers were not written from memory. For each case the database was queried directly from the host, the reply was saved, and its size and SHA-256 recorded in the case file alongside the endpoint that produced it. The case file is fixed before the question is ever put to fred, and a case is never edited to match a result.

What the suite checks, and what it found

The suite runs as six stages against the live service. Any gated stage that fails stops the run.

The suite has failed a run, and refused it. On the first automated run after the baseline was stored, on 2026-09-08, one of the nine answers did not cite the required UniProt accession for SOD1. The citation stage recorded the violation and the run was refused before the judge ever saw it. That answer is described under the limitations below; it is the reason this release exists in the form it does.

Three questions is a baseline, not a survey of what fred can do. They exist so that a later run can be compared against a stored result and a change detected, rather than assumed away.

What to know before relying on it

The limits of this release, in plain words.

How to connect

Four routes, plain HTTP and JSON, no SDK.

The service runs as a sealed, versioned container on one machine, listening on a loopback address. An application connects over that local address, sends a question, polls until the answer is ready, and reads the answer and its provenance record. fred itself is not modified by any application.

Authentication is optional. When a deployment sets a token, the three routes other than health require a bearer header and refuse without one; the health route is never authenticated.

The wire version

Send "wire_version": "1.2" on every POST and assert that the response carries the same value. fred accepts 1.0, 1.1 and 1.2, and answers 1.2 to all three; it will never tell a client it is behind, so a client that keeps sending an older version will keep working while silently reading a compatibility path.

The one-slot protocol

• Poll /v1/health until the current run identifier is null. That is how to avoid a refusal without a retry loop.
• POST the run. A 202 carries a Location header and the new run's identifier in state pending.
• A 503 means a run is already in flight and carries the occupying run's identifier. Its Retry-After: 60 header is a fixed constant and means nothing: do not sleep on it, poll instead.
• Poll the run every few seconds; the reference harness polls at five. A denser poll buys nothing, because the live counts lag a turn either way.
• On a terminal state, exactly one of result and error is present; a validator enforces that you never see both or neither.
• A terminal run stays retrievable for one hour after its last update, then returns 404. Persist what you need when you first read it. A run identifier that returns 404 sooner means the service restarted.

The request body

Required: the wire version and a non-empty prompt. Optional: a tenant identifier of 1 to 128 characters, logged but not enforced, and max_iterations between 1 and 200, default 30. The budget bounds turns, not tool calls: a tool-call turn and the answer turn are two. A run that exhausts it ends failed with the kind max_iterations_reached. Do not send a tools field: it is accepted, stored, and ignored, and every run is offered the full registry regardless.

A minimal exchange

curl -s http://127.0.0.1:8105/v1/health
-> {"wire_version":"1.2","status":"ok","fred_version":"0.3.0","current_run_id":null}

curl -s -X POST http://127.0.0.1:8105/v1/runs -H 'Content-Type: application/json' \
  -d '{"wire_version":"1.2","prompt":"<your prompt>","tenant_id":"compound2","max_iterations":30}'
-> 202 {"wire_version":"1.2","run_id":"<uuid>","tenant_id":"compound2","state":"pending"}

curl -s http://127.0.0.1:8105/v1/runs/<uuid>
-> {... "state":"completed", "result": {"final_response": "...", "tool_calls": [ ... ]}, ...}

That is the whole protocol. Everything else is what the fields mean and what can go wrong.

What a client should plan for

• There is no wall-clock ceiling on a run. Measured retrieval questions take roughly 30 to 55 seconds; a hung model call can block for 600 seconds per attempt.
• The slot can stick. If fred's own failure-recording call fails, the run stays in flight for the life of the process and every POST is refused until a restart, which loses every run.
• Any body over 500 characters reaches the client as malformed JSON, because the excerpt is cut mid-structure. Read the first key by string handling rather than parsing the excerpt unguarded.
• No tool retries an upstream rate limit. A rate-limited lookup is recorded as an error on that call and the run continues.
• A result from the protein lookup can describe an unreviewed database entry with full provenance. A client that takes an accession, a length, or a function from it should read the entry identifier: a reviewed entry carries a mnemonic, an unreviewed one carries its accession and organism.
• Files fred writes arrive root-owned on the host mount, and the service has been run on x86-64 only.

Status

Built, tested, deployed as a locked service, and driven end to end by the golden suite. Not yet connected to any application, and not yet set to restart automatically after the host machine reboots.

A consumer integration guide with the exact steps is provided to the application teams.