User Guide

AnnoBio is a workspace for turning biomedical literature and research records into structured, reviewable datasets. It supports text and multimodal data mining across abstracts, full-text PDFs, clinical notes, tables, and images. Typical tasks include extracting entities, relations, measurements, and supporting evidence; classifying records by relevance or study design; and normalizing terminology to standard identifiers. These operations can be combined into reproducible pipelines and assessed against expert-curated reference data.

This guide takes you through a complete workflow: configure LLM access, define an annotation task, build and run a pipeline, evaluate its output, revise the Prompt, and test the revised version. It also shows where the Agent Assistant can help while keeping scientific decisions under your review.

The worked example is gene–disease association extraction. For each abstract, the pipeline identifies the gene–disease relations asserted by the authors, retains a supporting quotation, and uses a short Process step to produce a tidy table. The output is then compared with pairs reviewed by a curator. Generate steps use a model and Prompt; Process steps apply explicit Python transformations. The same pattern can be adapted to literature screening, clinical trial annotation, evidence synthesis, and other biomedical data-mining tasks.

The example uses five short, synthetic abstracts so that every intermediate result is easy to inspect. Its scores demonstrate the workflow only; they are not evidence of performance on a research corpus. For a real study, develop the pipeline on a small reviewed sample and reserve separate records for final validation.

For a larger project to explore, open Gallery, select Kinase–Substrate Evidence Curation, and use Add to my account. You can also build the example yourself by following the steps below.

AnnoBio uses model access that you provide. In the browser, register or sign in and open Workspace. On desktop, launch the app and wait for its local backend to start. You can configure a model before creating a project.

The desktop app starts its local backend automatically. If model, Process, or evaluation actions are unavailable, open the bottom Log tab and confirm that the backend started successfully before changing the workflow.

Add and test a credential

In the browser, select LLM settings in the top bar. On desktop, open Settings → LLM settings…. Under Credentials, enter the provider, Model ID, and API key, then select Test. Do not continue until the credential passes. You can also connect an OpenRouter account. Credentials must be configured by you; the Agent Assistant cannot add them.

Choose defaults for Generate, Optimize prompt, and Agent Assistant; they may use different models. Record the provider and Model ID used for each experiment, because model choice can affect reproducibility. You can override the default with a tested model when creating a Generate or starting an optimization. Under Optimize, also select the Default review method when more than one method is installed.

Requests are sent to the provider you configure, and its usage charges and data-handling terms apply. Do not submit identifiable or restricted data unless that use is permitted. Begin with a small pilot sample to verify the instructions, schema, and model settings before processing the full corpus.

Checkpoint: at least one credential should show a successful test, and Generate should have a default model.

Before building the workflow, state the unit of analysis and the expected output. In this example, one input row is one abstract and one output row is one asserted gene–disease relation. Decide which fields are required, what counts as a positive relation, and how uncertain or negated statements should be handled. These decisions will guide the Dataset, Prompt, and reference annotations.

In the browser, create a project from the project picker in the top bar. On desktop, use File → New project… and choose where to save the project file. Give the project a name that identifies the research task. Its canvas will hold the data, Prompts, processing steps, results, and execution history.

Checkpoint: you should now have a named project with an empty canvas and a tested default Generate model.

Create a Dataset from the toolbar or, on desktop, from Edit → Create new dataset. For this example, each row represents one abstract and the columns are ID, Title, and Abstract. Keep a stable, unique identifier in every research Dataset. It is needed to trace an output to its source and to pair model outputs with reference annotations later.

The database picker covers literature, clinical trials, compounds, genes and variants, proteins, pathways, experimental data, species, and data snapshots. Online sources accept IDs, genomic intervals, or sequences as indicated by the form. Some sources require an API key. Study and structure imports provide metadata and download links. gnomAD variant IDs use GRCh38 coordinates.

Data snapshots are available in the desktop app. The web app offers online database APIs. For a desktop data snapshot, choose its file and click Download. Choose columns once it is ready. Existing downloads are reused. Imports keep up to the first 5,000 rows and show a notice if additional rows were omitted. The same truncation note is appended to the created Dataset description. Search column names in wide tables. The Downloaded button changes to Remove download on hover or keyboard focus. Source files are shared across projects. Deletions in the file manager are detected automatically; imported project tables remain available. Large pickle files require sufficient local memory unless a prepared Parquet copy is available.

Select the Dataset node to open it, then verify the import before building the pipeline. Confirm that one row corresponds to the intended unit of analysis, identifiers are unique, text has not been truncated, and file columns contain the expected files. Check missing values, duplicate records, worksheet selection, column types, and unexpected parsing. Correcting these problems now prevents them from being mistaken for model errors later. The Agent Assistant can also search supported external sources when you need to assemble a literature set.

Keep source data separate from manually reviewed reference answers. Once a saved History record refers to a Dataset, it may become content-locked so that the recorded run remains reproducible. Create a new Dataset version or an independent copy rather than altering a locked input.

Checkpoint: the canvas should contain an inspected input Dataset with one stable ID per source record.

Once the source Dataset is ready, begin in the Agent Assistant rather than assembling every downstream node manually. Open the Agent side bar and describe the task in the same way you would brief a coding agent: identify the Dataset, define one input and output observation, list the required fields, and state important inclusion, exclusion, and evidence rules.

Ask the Agent to build the first version

Use the Dataset disease_abstracts. Read Title and Abstract and propose a Prompt that returns one row per asserted gene–disease association, with gene, disease, and a short supporting quotation. Exclude negated associations. Then propose a Generate step and map the Dataset columns to the Prompt inputs. Show me all proposed changes before running anything.

Review the proposed Prompt text, output schema, connections, and selected model. Ask follow-up questions or request edits in natural language. Confirm the proposal only when it matches your annotation protocol; approve model or code execution separately.

Use the conversation to modify the Prompt

After running and evaluating the pipeline, return to the Agent with the relevant node names and observed failure pattern. Ask it to explain the evidence before proposing a change:

Inspect the unmatched rows in Evaluate pairs. Separate nomenclature errors from false positive relations, explain which Prompt instruction caused each pattern, and propose a new Prompt version. Preserve the original Prompt and do not apply or run the revision until I review it.

This conversational loop—describe, inspect, revise, and verify—is the recommended way to work with AnnoBio. The following chapters explain the Prompt, Generate, Process, and Evaluate objects in detail so that you can review the Agent's work and intervene precisely. See the full Agent workflow for proposal and execution controls.

Checkpoint: you should have either an Agent proposal for the first Prompt and Generate step, or a clear reason to build them manually in the next chapters.

Create a Prompt from the toolbar or, on desktop, from Edit → Create new prompt. Use a task-specific name, such as Extract gene–disease pairs, so that later versions remain identifiable.

Describe what to extract

Translate the annotation protocol into explicit instructions. Define the target relation, inclusion and exclusion criteria, treatment of negation and uncertainty, required evidence, and the behavior when no eligible relation is present. Avoid relying on specialist assumptions that are not stated in the Prompt. Use single-brace placeholders for values supplied by each input row:

You are curating gene–disease associations from biomedical abstracts.

Title: {title}
Abstract: {abstract}

List every gene that the abstract reports as associated with a disease.
Return one row per gene–disease pair, with a short quote from the abstract as evidence.

Each placeholder becomes a Prompt input that you will map to a Dataset column in Generate. Match placeholder names exactly. This first Prompt is intentionally incomplete: it does not specify how to represent alleles and variants or how to handle a negated association. The evaluation below makes those failures visible.

Choose the table you want back

Define an output schema with stable field names, precise descriptions, representative examples, and appropriate data types. The example returns gene, disease, and evidence. Specify expected nomenclature—for example, an HGNC gene symbol rather than a variant label. Enable Allow None only when a missing value is scientifically valid; otherwise it can conceal an extraction failure.

Choose Multiple output rows when one input may yield zero, one, or several observations, as in relation extraction. Choose One output row when every input should produce one annotation, as in document-level classification. This decision determines the shape of the results table and how it must later be evaluated.

Checkpoint: the Prompt should have two inputs, title and abstract, and a multiple-row schema with gene, disease, and evidence.

1. Open the Prompt, choose a tested model beside Create Generate, and create the Generate step.
2. Drag from the Dataset Output port to Connect data on Generate. Because this Generate was created from the Prompt, its Prompt connection is already present. If you create an unconnected Generate instead, also connect the Prompt to Connect prompt.
3. Open Generate. Under Map input columns to prompt inputs, map Title to title and Abstract to abstract.
4. Verify the connected Dataset, Prompt version, model, and every input mapping. For a first run, use the five-row example or another small pilot sample.
5. Select Run. Keep the window open to monitor progress, then inspect the completed results table.

Results appear as input rows complete. With a multiple-row schema, one abstract may yield several output rows; here, the BRCA1 abstract yields two relations. Check coverage across input IDs, inspect every output field, and open row details to examine the actual request and model response. During a pilot, do not judge quality from the first plausible-looking rows.

Read the output against the source text before continuing. In this run, APOE ε4 and LRRK2 G2019S mix gene symbols with allele or variant labels, while CLU is extracted from a sentence that explicitly reports no association. These are different error types and should not be collapsed into a single accuracy judgment. The next sections encode the expected answers and quantify the errors.

The node's History lets you revisit earlier attempts. If inputs change, an earlier result may remain visible as Historical; run the current configuration before treating it as the current output.

Checkpoint: all five input IDs should have completed, and you should be able to explain each suspicious output by returning to its source text and row details.

Add downstream steps when the research workflow requires more than one operation. For example, a gene–disease pipeline might tidy the extracted columns, validate gene symbols against HGNC or UniProt, and then use another Prompt to normalize disease mentions. Keep each step focused on one operation so that its inputs, outputs, and failures remain interpretable.

Use Process for table transformations

Use Process for deterministic table transformations that should be explicit and reproducible: selecting or renaming columns, filtering rows, joining tables, deduplicating records, or calculating derived values. In the desktop app, first open Settings → Python settings…, select an interpreter, and test it; the same setting is required for Match by code during evaluation. Create a Process from a Dataset or step output and write def process(df): to transform its pandas DataFrame. Return one DataFrame, or return a dictionary of named DataFrames to create output branches. For additional inputs, add df_<name> parameters and connect the corresponding input dots.

Run the Process on a small input and inspect the output columns and row count before continuing. Use a direct connection when the downstream step should always follow the current upstream result. Save to workspace instead creates a Dataset snapshot for independent inspection, editing, or reuse; downstream work from that snapshot will not automatically follow later upstream runs.

Choose how much to run

The right-click menu shows the actions relevant to the node's current state. An interrupted Generate may also offer Resume for that node alone. The bottom Run tab records execution outcomes.

Inspect the route

Open the Pipeline tab and read the selected route from source Dataset to final output. Select a step to locate it on the canvas. Where alternatives exist, choose the Prompt version or Generate that belongs to the analysis you intend to run. Give the route an informative name, then use Export Python Project when you need a standalone, inspectable representation of that selected computational route.

Checkpoint: the selected route should read Dataset → Generate → Process, and the Process output should contain the expected columns and row count.

Evaluation requires an explicit reference standard. Create a separate ground truth Dataset containing answers reviewed under a documented annotation protocol. Include the source identifier needed to associate each answer with its input. In this example, a curator records six expected relations for five abstracts in Reviewed pairs, with ID, Gene, and Disease columns.

For a research study, resolve ambiguous cases before scoring and, where feasible, measure agreement between annotators. Keep the data used to revise the Prompt separate from a held-out validation set. Evaluation cannot compensate for inconsistent reference labels.

1. Open a completed Generate and click Create Evaluate.
2. On the canvas, drag the reference Dataset Output to Connect ground truth on Evaluate. Ground truth is connected on the canvas rather than selected from a dropdown in the Evaluate window.
3. Define input pairing so that predictions are compared only with answers from the same source. Here, under Match by rules, use + Add rule to require Input: ID to equal Ground truth: ID.
4. Add output matching rules for every field required for a correct observation. Here, both gene and disease must match. Review case sensitivity, normalization, and missing-value behavior.
5. Select Run, then inspect both the summary metrics and the row-level matches.

Rules can combine conditions with AND and OR. Choose matching that reflects the scientific meaning of the field rather than merely maximizing the score. Available options include fuzzy and semantic text matching; HGNC for human genes; PubChem and ChEBI for compounds; RxNorm for drug names; MeSH and MONDO for diseases or conditions; and GO for gene ontology terms. Use a normalizer only when it is valid for the field and study protocol. Use Match by code when the protocol requires custom logic, and preserve that code with the project.

Interpret precision as the proportion of predicted relations that are correct, recall as the proportion of reference relations recovered, and F1 as their harmonic mean. Always inspect the comparison rows as well: the same score can result from scientifically different failures. Here, APOE ε4 and LRRK2 G2019S are nomenclature mismatches, while CLU is a false positive caused by negation. Check pairing rules and reference labels before attributing every mismatch to the Prompt.

The Optimize checkbox column controls which comparison rows contribute to the displayed metrics and are sent to Prompt optimization. Keep all relevant rows selected for a complete evaluation; use a subset only when that exclusion is intentional and documented.

Each Evaluate run has its own History. Changing its inputs or rules leaves the previous result visible with an update notice; click Run to score the new configuration.

Checkpoint: the example evaluation should pair outputs by ID, require both gene and disease to match, and show four matched predictions out of seven.

Optimize only after you have inspected the evaluation and confirmed that the reference data and matching rules are sound. Confirm the Default review method under LLM settings → Optimize. Then, from the completed Evaluate result, choose a tested model beside Optimize prompt and start the analysis. The resulting Optimize node records the method, analysis, and proposed changes for that specific evaluation attempt.

Inspect the findings

For each finding, examine the failed examples, the stated diagnosis, and the exact Prompt text that would change. Decide whether the proposal expresses a general annotation rule or merely accommodates the few development examples. Reject changes that weaken the evidence standard, introduce unsupported domain assumptions, or conflict with the written annotation protocol.

Verify before keeping a change

Use Click to Verify, where offered, to test a suggestion on its associated examples. This is a local check, not independent validation. For supported local edits, an unsuccessful check may offer Click to Optimize to search for a better candidate. Available actions depend on the selected method and suggestion state.

Use Accept to include a suggestion in the working Prompt, or Revert to remove it. Click Apply to create a new Prompt version from the selected changes. The source Prompt remains available for comparison.

An Optimize node stays tied to the Evaluate History it was created from. If you change the reference answers, rules, or source result and run Evaluate again, start a new Optimize from that new evaluation. Resume an interrupted Optimize when you want to continue the original analysis.

Checkpoint: applying the accepted suggestion should create a new Prompt version; the original Prompt and its evaluation must remain available.

1. Open the new Prompt version and create a Generate using the same model, model settings, and input Dataset as the baseline.
2. Run it and evaluate the output against the same development reference and matching rules.
3. Compare metrics, row-level failures, and previously correct examples. An improved aggregate score can conceal a new systematic error.
4. Freeze the candidate Prompt, then evaluate it once on reviewed records that were not used for Prompt development or optimization.

The bottom Prompt tab shows Prompt families and their Evaluate & Optimize steps. Select a version's Compare icon to inspect changes from its predecessor. Select the version you intend to use in the Pipeline route before exporting it.

In the example, version 2 matches all six reviewed pairs. This is expected because the revision was derived from those same five abstracts; the result is a development-set score, not an estimate of generalization. Report performance on a separate validation set, including omissions, false positives, and clinically or scientifically important subgroups. Retain the previous Prompt version and document the model, Dataset versions, matching rules, and date of the final run.

Checkpoint: you should have comparable baseline and revised runs, plus a plan to evaluate the selected Prompt on held-out reviewed records.

The Agent Assistant can inspect the open project and propose work through natural-language requests. Treat it as an auditable research assistant rather than an autonomous decision maker: name the data and nodes involved, define the expected output, state scientific constraints, and specify whether you want an explanation, a proposal, or an execution. Review proposed changes and generated content before they become part of the analysis.

Source searches cover supported biomedical and literature services, plus Wikipedia when explicitly requested. They are source-specific queries rather than general web browsing. Record the query, filters, and retrieval date when search results contribute to a review corpus. For troubleshooting, the Agent can inspect exposed node and task information, but it cannot read the desktop Log panel.

Use the side-bar button in the top bar (labelled Toggle Agent Side Bar) to open the Agent Assistant, then choose or add a conversation. It uses the Agent model configured in LLM settings. You can start a conversation before opening a project and ask the Agent to help create one when your task needs it.

An empty conversation shows a welcome card with four starting points: learn AnnoBio, find data, build a pipeline, or improve a prompt. Choose one to fill the message draft, edit it, and send when ready. The close button dismisses the card for that conversation. On desktop, you can also drag local files or folders into the chat.

1. Describe a concrete task

Name the relevant Dataset or node, define the unit of analysis and output fields, and state inclusion, exclusion, and evidence requirements. Ask the Agent to show its proposed structure before running a model or changing project content. For example:

Use disease_abstracts to extract gene–disease pairs. Read Title and Abstract and return gene, disease, and a short evidence quote. One abstract may contain several pairs. Show me the proposed nodes before running anything.

2. Inspect the proposed changes

The Agent can read project information to plan its work. Changes to project content are presented as proposals for you to review and confirm. Check the affected nodes, Prompt wording, schema, input mappings, connections, and model selection against your protocol. Ask for a revision when a proposal changes the scientific meaning of the task or leaves a decision implicit.

3. Confirm execution separately

Model and code jobs use execution cards. Review the target and scope before starting. A proposal to create a step and a request to run that step are different actions. When several tested models are available, state your choice or answer the Agent's model question.

4. Check the actual output

Open the created nodes and inspect their actual inputs, configuration, and results. Confirm record counts and review representative outputs against their sources. For optimization, inspect the new Prompt version and evaluate it as described above. If a job stops or fails, ask the Agent to inspect its state before retrying. A proposal, accepted change, and completed execution are distinct events.

Configure provider credentials, default settings, and Python yourself. Use the interface to select Pipeline routes, publish to Gallery, open or merge projects, and perform other actions the Agent does not expose. The Agent respects the same content locks as the canvas.

These features are available in the desktop app. Use them when the source material is a local table, document collection, or existing analysis project. Review institutional data policies before attaching sensitive, unpublished, or identifiable material.

• Attach files: use the paperclip beside Send, or drag files into the conversation. The Agent can inspect attached tables and read supported text, code, and document content. Ask it to import a table, or a batch of images or PDFs, as a Dataset in the open project.
• Provide a path: include a file or folder path in your message, or drag in a folder. Sending that path grants read access for this conversation. An additional folder request appears as an Allow / Deny card.
• Adapt an existing project: ask it to inspect the README, data format, and relevant processing code, then propose how to reproduce that workflow with Datasets, Process steps, and Prompts.

Local access is read-only and limited to paths you provide or approve. The Agent can adapt code into a proposed Process; it cannot modify source files or execute the original project's scripts. Inspect the proposed Process before running it. Only share content that your ethics approval, data-use agreement, and configured model provider permit you to transmit.

Supported inputs include common spreadsheets and JSON/JSONL, text and code files, and readable text from PDF, Word, PowerPoint, and OpenDocument documents. Image attachments can be imported into a Dataset; attachment inspection alone does not interpret their visual contents. Use a compatible Generate model for image annotation.

For a large folder, identify the entry point and relevant files first. A conversation can read or search the contents of up to 100 distinct local path files; a folder import supports up to 500 files and 512 MB. A project must be open before importing a Dataset. On desktop, the Agent can also propose creating a project when none is open; you choose the save location.

Under LLM settings → Optimize, the Default review method control lists the optimization methods installed on your instance; it appears when more than one method is available. Begin with the default when you want interpretable, issue-guided edits. Use another method only when its search strategy, computational cost, and use of examples fit the study design.

Methods differ in search strategy, model usage, number of calls, and available suggestion actions. Optimization can be substantially more expensive than a single Generate run. Regardless of method, inspect the resulting Prompt and evaluate it on reviewed data that were not used to drive the search.

Browser projects are saved to your account; use the project picker to reopen, duplicate, or merge them. Desktop projects are local project files; use File to open one, Save as…, or merge another project.

Duplicate a project before an independent experiment or major methodological change. Merge only when you intend to bring another project's nodes onto the current canvas. Use History to inspect prior attempts, and create new Prompt or Dataset versions whenever the original configuration must remain recoverable.

Use the Pipeline panel's Python export for a selected computational route. Use Publish to Gallery to submit a project for public reuse; submissions are reviewed before appearing in the public Gallery. Browser users must first add their name in Profile. Before export or publication, remove restricted data and credentials, check Prompt and Dataset versions, and inspect results and conversation content. Record the model identifiers and reference-data provenance needed to interpret or reproduce the workflow.

Return to pipeline setup, evaluation and optimization, or Agent capabilities as you continue your work.