Omnisci

omnisci: you are the scientist, the CLIs are the instruments

You do the science yourself. 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. No model API is called at any point. Your own multimodal read is the perceiver.

Where the commands live

The CLIs ship inside this skill. Set this once, at the start of the session, and use it in every command:

export OMNISCI=~/.claude/skills/omnisci/bin        # or wherever this skill is installed
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.

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 gate_cli.py record, which banks a script's stdout. 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. Prefer hits that carry a DOI, and discard the off-topic ones 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 images. Read each PNG yourself, then record what you saw:

python3 $OMNISCI/evidence_cli.py ingest --task <case> --call <id> --answers '{"1": "what you actually saw"}'

The key in --answers is the id inside that call's own pending list, which starts at 1 for every call. 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.

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).

Check every figure with your own eyes before compiling: no clipped or colliding labels (a colorbar label printed over an axis label is a real failure seen in the wild), and never rainbow colormaps (viridis/plasma/jet); colour by a single-hue sequential ramp or a few discrete colours.

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.

Then:

python3 -u $OMNISCI/gate_cli.py record --task <case> --script host/analysis/<name>.py

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. There is no default timeout; set --timeout <seconds> if you want one.

Read your own figures afterwards to confirm they are not broken. 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.

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
python3 $OMNISCI/lit_cli.py bib --task <case> --picks picks.json

A paper needs at least 15 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. The compile step counts the references actually printed in the PDF and reports refs_count red below 15; that is a label, not a compile error, but a thin bibliography makes the related-work discussion visibly weak.

--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. A \cite to any key outside the bib is stripped at assembly, so a hallucinated key silently loses its citation.