Omnisci

omnisci: DeepSeek is the scientist, the CLIs are the instruments

Do the science in the current CLI session. The python here does only what a model must not do by hand: render raw data into something viewable, run analysis code, fetch real references, assemble LaTeX, and enforce the gates. These CLIs never call another model API. DeepSeek V4 Flash remains the scientist and author. Because the official DeepSeek endpoint accepts text only, the CLI's view_image sends pixels to its fixed, vision-capable sidecar and returns only the factual observation to DeepSeek. This follows OmniScientist's own text-backbone plus VISION_SIDECAR design.

Where the commands live

The CLIs ship inside this skill and the launcher sets OMNISCI. Confirm it once and use it in every command:

test -n "$OMNISCI" && test -f "$OMNISCI/evidence_cli.py"
python3 $OMNISCI/evidence_cli.py --help            # confirm before going further

--task takes a case directory (absolute paths always work), or a bare name that resolves under $OMNISCI_CASES or the engine's bundled examples/. Every other path you pass (a script, a figure, a .tex, a sections.json) is resolved relative to the case directory.

Every command echoes the case it resolved. Check it on your first call. A bare name can land on a bundled example that already holds someone else's recorded runs, and the gate would then happily ground your paper's numbers against their ledger. When the case is the user's own folder, pass its absolute path.

Three state-changing steps are OmniScientist tools, not shell commands: omnisci_record, omnisci_bib, and omnisci_compile. Call them through the tool protocol. They run the packaged CLIs with argument arrays and return receipts that the final delivery verifier binds to the current files. A bash call to the same Python CLI may help diagnose a failure, but it cannot satisfy final delivery.

Before the loop: is there a case?

A case is a directory holding a series.json. Bundled demos have one. A real user almost never does: they have a folder of images, recordings or volumes, and a question. Build the case first, from their folder:

python3 $OMNISCI/case_cli.py inspect --dir ~/their_folder      # what is in there, what modality, what labels
python3 $OMNISCI/case_cli.py init --dir ~/their_folder \
    --role "a histopathologist reading H&E-stained sections" \
    --subject "a tissue microscopy field" \
    --direction "Find a concrete, testable question these fields can answer, choose the method yourself, and run real code to test it."

Before initialising a new case, check whether one already exists nearby: users often point at the data/ subfolder of a case whose series.json sits one level up (list the parent of the folder they named; the CLIs also search upward, adopting a parent only when its series.json actually lists files under that folder).

inspect never writes; run it first and tell the user what you found. init writes series.json into their folder and nothing else (use --out to build the case elsewhere and symlink the data instead). Files are routed to a modality by extension, and each item's label is taken from its containing folder, so tumour/a.png is labelled tumour; pass --label-from none when the folders mean nothing.

The three fields are yours to write, and --direction is the one that matters: state the data and the goal, and do not prescribe the method. "Compare mean intensity between the two groups" produces a worse paper than "find a concrete, testable question this data can answer". Ask the user for the framing if their request is too thin to write it, then show them the direction you wrote before running.

Three rules that are not negotiable

1. Every number in the paper must come from a recorded run. Numbers enter only through the omnisci_record tool, which runs the script and banks its stdout with a session receipt. This includes setup values: if you write that the green class covers 458 to 532 nm, that is a claim about the data and your script must print it. Never carry a number you computed in your head. gate_cli.py check blocks the paper otherwise.
2. Every citation must be a paper that exists. They come from lit_cli.py search and only from there. Every final pick needs a DOI: bib resolves it again and writes hash-bound verification provenance that the final gate checks. Discard the off-topic hits a broad query drags in.
3. Look at the evidence before forming a hypothesis, and ingest what you saw. A rendered image you never ingested is an image nobody read, and the gate now blocks on it.

The loop

0. See the data

Read the case's series.json first. Field names vary: the open research brief may be called direction, request or idea_hints, and role / subject / property describe the scientist you are playing. There is no fixed schema, so read what is actually there.

Then ask what this case unlocks, and read the returned schema rather than copying the shapes below, since arguments differ per tool:

python3 $OMNISCI/evidence_cli.py tools --task <case>

look_at_image takes files (an array). look_at_signal, look_at_audio, look_at_video, look_at_3d and look_at_trajectory each take file, a single path, one call per item. analyze_* tools return numbers immediately and involve no vision at all; use them freely, they cost nothing.

python3 $OMNISCI/evidence_cli.py run --task <case> --tool look_at_signal --args '{"file": "data/x.npy", "question": "..."}'

A look_at_* call returns status: needs_vision with a pending list. For every pending item, call OmniScientist's view_image tool on its image path and ask its exact question. The tool binds its pixel observation to the pending request with a receipt. Only after the real image has been returned, ingest that receipt:

python3 $OMNISCI/evidence_cli.py ingest --task <case> --call <id>

Do not hand-write --answers: ingest rejects text that differs from the view_image receipt. The request id inside each call still starts at 1; it is not the call id and not a running total.

Ingest immediately after each call rather than batching at the end; a call left pending is indistinguishable from never having looked. The budget is 12 images, not 12 calls: look_at_image with three files spends three of them, while one look_at_3d spends one even though the render it returns holds six panels. Every call prints used=n/12, so watch it. Raise it with --budget on run if the case needs more, and spend it on items you chose for a reason.

This is the whole point of host mode. A non-image modality is rendered to a PNG by python first, and you read that PNG the same way. Describe what is in the picture, not what you expect; if a render looks blank or degenerate, say so rather than inventing structure.

1. Form a hypothesis

State one falsifiable question that follows from what you saw and from the case's brief. Choose the method yourself. In an interactive session, tell the user the question before spending their time on it; in a non-interactive run, put it at the top of your final report.

2. Run real analysis

Write a python script under <case>/host/analysis/, print every decisive number as name = value, and save figures under <case>/host/figures/. The script runs with cwd set to the case directory, so resolve paths from __file__ if you need to be safe. Then call omnisci_record with script set to host/analysis/<name>.py; pass argv only when the script actually takes positional arguments. Do not run gate_cli.py record through bash: it produces a workspace ledger line but no trusted session receipt, so final delivery rejects it.

Print more than you think you need: every constant, window, threshold and count that will appear in the prose. Output is streamed as the script runs, so progress lines are useful, and it is banked verbatim unless it passes 2 million characters, at which point the middle is dropped and you are warned. The tool timeout is at most 600 seconds; set its timeout argument lower for a deliberately bounded analysis.

Only the latest run of each script-and-arguments invocation is active. A non-zero rerun invalidates its earlier success, and editing the script invalidates every result recorded from its old bytes. Failed or stale stdout can never ground a paper; fix the script and record it successfully again.

Call view_image on every analysis figure afterwards to confirm it is not blank, clipped, mislabeled, or misleading, and that no two labels collide (a colorbar label printed over an axis label is a real failure seen in the wild). Never use rainbow colormaps (viridis/plasma/jet); colour by a single-hue sequential ramp or a few discrete colours. Report a null result as a null result; a paper that honestly resolves nothing is acceptable, a paper that dresses a null as a discovery is not.

Figure shape contract: a single-column figure prints WIDE and SHORT, height about 0.43x its width (think 10:4.3); a figure meant to span both columns doubles the width at the SAME height, never the height. A sparse chart (a handful of bars or points) gets a smaller height, not a bigger canvas, and two half-empty plots belong in one multi-panel row rather than two figures. Compile lint reports fig_aspect red on anything taller than these bands (col 0.58, wide 0.30 of the width).

Author figures at their FINAL printed size, not on a giant canvas: a single column prints ~3.4in wide (figsize about (3.4, 1.5), fonts 8-9pt), a both-columns figure ~7in. A 2000px canvas squeezed into one column shrinks its text several-fold and lint reports fig_print_size red. Include with width=\linewidth, and give side-by-side panels a both-columns figure rather than cramming them into one column.

3. Get real references

python3 $OMNISCI/lit_cli.py search --query "<specific terms from your subject>" --n 10     # explore
python3 $OMNISCI/lit_cli.py search --doi 10.1038/s41597-022-01721-8                        # pin one you decided on

A paper needs at least 12 references, and 15 to 25 is the normal range. One search does not get you there: its recall covers one subtopic, so run several, one per angle. For a typical study that means the dataset or benchmark you used, the existing methods for the task itself, the metric or statistical machinery you rely on, and the field each control task belongs to. Concatenate every hit you want into one picks.json. omnisci_bib tells you the count it wrote and warns when it is under the floor; a thin bibliography is not a compile error, it just makes the related-work discussion visibly weak.

Write the combined picks under the case, for example host/picks.json, then call omnisci_bib with that relative path. Do not invoke lit_cli.py bib through bash; only the dedicated tool creates the session receipt required for delivery.

--n is how many hits you get back in total. Free-text recall is not stable: the same query can return a paper on one call and not the next, so once you have chosen a reference, re-fetch it with --doi and build picks.json from those. picks.json is a JSON list of hit objects exactly as search printed them, one array holding every reference you want; each search call prints its own array, so concatenate them yourself rather than expecting the tool to accumulate.

search does not return bib keys, it returns papers; the keys are minted by bib, so run bib first and cite the keys it prints. bib rejects picks without a DOI and re-fetches each DOI instead of trusting fields in picks.json. A \cite to any key outside the bib is stripped at assembly, so a hallucinated key silently loses its citation; a changed or hand-written bibliography fails the gate's provenance hash.