DocsPlatformCore concepts

Core concepts.

Essarion is a single platform behind three product surfaces, and every surface reuses the same small vocabulary. This page is that vocabulary. Read it once and the rest of the docs will read like a single document — because the same project, the same run, the same source, mean the same thing whether you're in the research UI, reading the encyclopedia, running a study, or hitting the API.

§ 01Containers and execution

Most of Essarion's nouns describe one of two things: a place where work lives, or a thing that runs. The four below are the load-bearing terms for both.

Project

A project is a tenanted container for related work. It is the unit of grouping the platform organizes everything else around — runs, files, sources, documents, history all attach to a project, and a project belongs to exactly one user (or, in shared workflows, to that user's workspace).

Think of a project the way you'd think of a research dossier or a folder on a shared drive: the brief, the references gathered along the way, the drafts produced, the chat history with the agent that built them, the audit trail of every action — all in one bounded place. When you start a new piece of work, you start a new project. When you come back tomorrow, the project is exactly where you left it.

Run

A run is a single execution of a workflow. Every research query is a run; so is every study Essarion Science carries out. A run has a status (pending, in-progress, completed, failed), an ordered set of phases, a persistent timeline of everything that happened during it, and a stable identifier — the request_id — that you can use to retrieve it later.

Runs are first-class. Once started, they persist whether or not you stay connected. You can subscribe to a run while it streams, fetch its full timeline after the fact, share a link to it, or replay it in the UI. The same run object backs the live view in the research app and the JSON returned from GET /api/v1/runs/{request_id}.

Phase & step

A run is composed of phases — the discrete stages it moves through on its way from question to answer. In the research engine, a deep query passes through up to twelve of them: analyze, plan, search, scrape, screen, analyze, cite, synthesize, and a few finishing passes around them. Each phase is a step on the timeline; each step has its own status, inputs, outputs, and timing.

Phases are not implementation details. They're how the platform makes the work legible. When you watch a run unfold, you're watching its phases tick through. When you debug a slow run, you're looking at which phase took the time. When you cite Essarion's reasoning to a stakeholder, you're pointing at a step.

Reasoning chunk

A reasoning chunk is a streamed fragment of the model's reasoning, attached to a step. As an agent thinks through a phase, its working notes are surfaced as chunks — short blocks of text that arrive in order over the stream, then are persisted against the step they belong to.

Chunks are how the platform shows its work in real time without waiting for a phase to finish. They're also how the timeline stays interesting after the fact: a completed run isn't just an answer, it's an annotated trace of how the answer was reached.

§ 02Research objects

The next four terms describe what comes out of a research run — the discovered evidence, the formatted bibliography, and the long-form artifact you actually keep.

Source

A source is a discovered URL with metadata. The research engine builds one for every page it reaches: title, domain, snippet, the full scraped text it extracted, and a set of scores. The scores capture credibility (is the publisher trustworthy), relevance (does it actually answer the question), recency (how fresh is it), and an overall composite the screener uses to decide whether the source survives into the final analysis.

Sources are searchable, reusable, and — if you keep them — yours. A source discovered in one run can be referenced in another, pulled into a project's library, or exported as a citation.

Citation

A citation is a formal bibliographic record built from a source. Where a source is the raw evidence, a citation is the publication-ready reference. The platform produces them in seven formats out of the box: MLA, APA, Chicago Notes, Chicago Author-Date, IEEE, Harvard, and BibTeX.

Citations are emitted alongside synthesized answers, available individually through the API, and exportable in bulk for projects that need a real bibliography at the end. They are the difference between a chatbot's gestured-at "according to some sources" and an answer you can hand to a reviewer.

Document

A document is a markdown artifact owned by a project. Notes, drafts, briefs, memos, summaries — anything the user or an agent writes down inside a project lives as a document. Documents are versioned, searchable within their project, and can be exported.

Documents are how a project accumulates value over time. A run produces an answer; a document is where that answer is shaped, edited, combined with other answers, and eventually shipped.

§ 03Study runtime

Inside Essarion Science, four more terms describe how a study is actually run: where the data comes from, what the engine can compute, how hard it is allowed to work, and what it may call a result.

Connector

A connector is a typed adapter onto one public scientific database — PubMed, GEO, ChEMBL, UniProt, the PDB, and nine others. Connectors return records, not summaries of records, and every one of them is key-free. Each can be switched on or off per run, so the same account can run a narrow study and a broad one back to back. The full roster is in Data sources.

Skill

A skill is a packaged computational-biology capability the engine can invoke — sequence tools (GC content, translation, ORF finding, pairwise alignment) and single-cell QC (per-cell metrics with outlier flagging). Where a connector fetches, a skill computes.

Tool

A tool is one action the planner may take, declared with what state it needs, what state it produces, and what it costs in tokens, wall time, and external calls. Retrieval, computation, statistics, reflection, and synthesis are all tools. The planner chooses among them each iteration rather than following a fixed script — see The workbench.

Depth mode

A depth mode — scan, deep_dive, or exhaustive — sets the literature pool, the evidence thresholds a claim must clear, the iteration and wall-clock ceilings, and which optional tools are available. It is the single knob that trades time for rigour.

§ 04Identity and sessions

The last group of terms is about who is acting and how the platform knows.

API key

An API key is a programmatic credential tied to a user. Every key is prefixed esk_, generated server-side, and shown in plaintext exactly once at creation; the platform stores only a SHA-256 hash. Keys can be revoked or marked inactive, and every use updates a last_used_at timestamp so dormant keys are easy to spot.

API keys are the canonical way to authenticate against the platform from your own code.

Session

A session is a browser session, represented by a JWT cookie set after sign-in. It carries the user identity for the product UIs. Sessions are HTTP-only and expire after a fixed window; signing out rotates the cookie immediately.

Sessions and API keys are two doors into the same identity — one for humans, one for code.

Workspace session

A workspace session is an ephemeral binding of a user to a project. When you open a project, the platform creates a workspace session that scopes reads and writes to that project's documents, that project's runs, and that user's permissions. When you leave, the session ends.

Workspace sessions are how the platform keeps tenants isolated even when many projects share the same underlying machinery.

§ 05Where this vocabulary appears

Every page that follows assumes the terms above. A few starting points if you want to see them in context: