# Mirobody documentation

> Mirobody is a health data engine: it collects readings from labs, wearables and
> genetic tests, standardizes them to canonical codes (LOINC · UCUM · FHIR R4), and
> answers questions over them with an agent. Three stages: ① Collect → ② Standardize
> → ③ Answer.

Two ways to run it, documented in the two sections below: the hosted API platform
(OpenAI-compatible `/v1`), and the open-source engine you deploy yourself (`/api/*`
plus an `/mcp` endpoint). Every page below is also published in Chinese at the same
path under `/zh/`.

## Cloud

### Getting Started

- [Introduction to Mirobody](https://docs.mirobody.ai/en/api-reference): What Mirobody is, the three stages it runs, and how to choose between Mirobody Cloud and self-hosting.
- [Quickstart](https://docs.mirobody.ai/en/api-reference/quickstart): Three steps: collect your data, watch it standardize, then open Answers.
- [Choose Your API](https://docs.mirobody.ai/en/api-reference/choose-your-api): Answers API vs Agent API — pick the right surface in one minute.
- [API Overview](https://docs.mirobody.ai/en/api-reference/overview): OpenAI-compatible health-data API — base URL, auth, multi-tenancy, retention, errors.
- [Models](https://docs.mirobody.ai/en/api-reference/models): GET /v1/models — list the available capability tiers.

### Data

- [Files / Photos](https://docs.mirobody.ai/en/api-reference/files): POST /v1/files, GET /v1/files, DELETE /v1/files/{file_key} — upload reports, retrieve extracted text, list, and delete.
- [Structured Records](https://docs.mirobody.ai/en/api-reference/data): POST /v1/data, GET /v1/data, DELETE /v1/data — write, read, and erase structured health records.
- [Narrative Text & Reports](https://docs.mirobody.ai/en/api-reference/extract): POST /v1/standardize — lab report in, standardized indicators out; dry-run by default.
- [How Standardization Works](https://docs.mirobody.ai/en/api-reference/standardization): How structured readings become coded, unit-normalized, queryable data.
- [Data Lifecycle](https://docs.mirobody.ai/en/api-reference/lifecycle): Retention, session cleanup, and Subject offboarding — how data leaves the platform.

### Agent API

- [Agent API (Responses)](https://docs.mirobody.ai/en/api-reference/responses): POST /v1/responses — OpenAI Responses-compatible agent surface: client tools, stored conversations, previous_response_id chaining.
- [Backbone Mode](https://docs.mirobody.ai/en/api-reference/backbone-mode): Run the Agent API as a bare LLM backend: mode:\"model\", the builtin_tools allowlist, and the full tool_choice contract.
- [Function Calling](https://docs.mirobody.ai/en/api-reference/function-calling): Built-in server tools + your own client function tools on the Agent API, with both handoff continuation styles.
- [Structured Output](https://docs.mirobody.ai/en/api-reference/structured-output): text.format — constrain the model to JSON (json_object) or a JSON Schema (json_schema) in backbone mode.
- [MCP Servers](https://docs.mirobody.ai/en/api-reference/mcp-servers): Bring your own remote MCP tools into the agent turn — OpenAI-native tools entry on the Agent API.
- [Streaming](https://docs.mirobody.ai/en/api-reference/streaming): response.* SSE events on the Agent API, including the mirobody_tool_call side-channel.
- [State & Memory](https://docs.mirobody.ai/en/api-reference/state-and-memory): How store, previous_response_id, session_id and data retention compose on the Agent API.

### Answers API

- [Answers API (Chat Completions)](https://docs.mirobody.ai/en/api-reference/chat): POST /v1/chat/completions — a closed, grounded completion over the Subject's real health data.
- [Use the Answers API as a Tool](https://docs.mirobody.ai/en/api-reference/use-as-a-tool): Cookbook: wrap the Answers API as one tool inside your own agent (openai-agents SDK / LangChain).

### Regions & Integration

- [Regions Overview](https://docs.mirobody.ai/en/api-reference/regions/overview): Pick the cluster that matches your users
- [China Region](https://docs.mirobody.ai/en/api-reference/regions/china): China production endpoints and regional differences.
- [Global Cluster](https://docs.mirobody.ai/en/api-reference/regions/global): api.mirobody.ai — the primary cluster.
- [SDK Examples](https://docs.mirobody.ai/en/api-reference/sdk-examples): End-to-end /v1 examples in curl / Python / Node.js — Answers, Agent (Responses), data, files.
- [Rate Limits & Quota](https://docs.mirobody.ai/en/api-reference/rate-limits): Per-key request rate limiting and the per-account usage quota.
- [Privacy & Compliance](https://docs.mirobody.ai/en/api-reference/compliance): Regional isolation, data controls, and security-review resources.

## Open Source

### Getting Started

- [Self-Host Mirobody](https://docs.mirobody.ai/en/self-host): Run the Mirobody engine on your own infrastructure: what you get, the three stages, how the data flows, and how to extend it.
- [Quickstart](https://docs.mirobody.ai/en/quickstart): Clone Mirobody, run ./deploy.sh, sign in at localhost:18060, and add an LLM key.
- [Installation](https://docs.mirobody.ai/en/installation): Three ways to install the Mirobody Python engine: Docker Compose, a local Python environment, or the PyPI package.
- [Configuration](https://docs.mirobody.ai/en/configuration): How the Mirobody engine resolves configuration: the three layers, automatic secret encryption, and every key in config.yaml grouped by what it does.

### The Engine

- [The Engine as a Library](https://docs.mirobody.ai/en/engine): pip install mirobody: offline indicator resolution, one-call document parsing, and the install layers between a numpy-only library and the full chat server.
- [Architecture Overview](https://docs.mirobody.ai/en/concepts/architecture): What the Mirobody Python engine is made of: three steps side by side over one shared infrastructure layer and one thin HTTP layer, running as two processes.

### ① Collect

- [Pulse Provider System](https://docs.mirobody.ai/en/concepts/providers): How Pulse plugs data sources in: the platform/provider split, the BasePullProvider contract, link types, scheduled pulls, and normalisation to StandardPulseData.
- [Provider Overview](https://docs.mirobody.ai/en/providers/overview): The data sources that actually ship with the engine: four theta providers, the Apple Health importer, what switches each one on, and which config keys have no provider behind them.
- [Using Providers](https://docs.mirobody.ai/en/providers/using-providers): The real /api/v1/pulse routes: fill in a provider's OAuth keys, connect an account by browser or by form, see what a user has linked, and let webhooks or the pull scheduler bring the data in.
- [File Processing](https://docs.mirobody.ai/en/concepts/file-processing): How an uploaded document becomes text, a summary and health readings: the supported formats, tiered vision-LLM extraction, content-hash deduplication, and the keys that control it.

### ② Standardize

- [Health Indicators](https://docs.mirobody.ai/en/concepts/indicators): ② Standardize: the offline resolver, the concept graph, the 300-member indicator registry, unit conversion at ingest, and how resolver coverage is measured.
- [Data Flow](https://docs.mirobody.ai/en/concepts/data-flow): The three intake paths health data enters Mirobody through, the two tables it lands in, the scheduled aggregation over it, and the single tool the agent reads it back with.

### ③ Answers

- [Agent Types](https://docs.mirobody.ai/en/tools/agents): DeepAgent and BaseAgent — who runs the tool loop, what each does with a turn, and how to configure their providers, prompts and tools
- [Tools & Agent Overview](https://docs.mirobody.ai/en/tools/overview): How agents, runtime-discovered Python tools, skills, and the MCP endpoint fit together
- [Built-in Tools](https://docs.mirobody.ai/en/tools/built-in): The four MCP tools the engine ships — terminology, health records and genetics — plus what DeepAgent gets from its harness.
- [Mirobody MCP Server](https://docs.mirobody.ai/en/tools/mcp-integration): The /mcp endpoint — local clients, remote HTTPS access, personal URLs and OAuth
- [Agent Skills](https://docs.mirobody.ai/en/tools/skills): A skill is a directory holding one SKILL.md — served to DeepAgent through deepagents' native SkillsMiddleware, with progressive disclosure.

### Building on Mirobody

- [Adding Custom Tools](https://docs.mirobody.ai/en/tools/adding-tools): Drop a .py file into a tool directory, restart, and the engine turns your function into an MCP tool
- [Building a Provider](https://docs.mirobody.ai/en/development/provider-integration): Write a BasePullProvider subclass and drop it into providers/: the factory, ProviderInfo metadata, credential validation, the OAuth flows, scheduled pulls, and normalisation to StandardPulseData.
- [Garmin Provider Example](https://docs.mirobody.ai/en/examples/garmin-provider): The decisions behind the shipped Garmin provider: the two-stage OAuth 1.0a link, why it registers no pull task, how webhook payloads deduplicate, and mapping fields as data rather than branches.
- [Provider Testing](https://docs.mirobody.ai/en/development/provider-testing): Verify a Pulse provider two ways: unit-test the mapping offline with pytest, and drive the live Pulse routes on a running server.
- [Development Setup](https://docs.mirobody.ai/en/development/setup): Run the Mirobody Python engine from a source checkout: venv, editable install, Postgres and Redis in Docker, and the test suites.
- [Contributing](https://docs.mirobody.ai/en/development/contributing): How to report issues, propose features, and land a change in the Mirobody Python engine.

### Deploy

- [Docker Deployment](https://docs.mirobody.ai/en/deployment/docker): How deploy.sh builds the image and what compose.yaml actually declares: four services on a fixed subnet, four named volumes, and dependencies installed at container start.
- [Production Deployment](https://docs.mirobody.ai/en/deployment/production): What has to change between a deploy.sh stack and a production one: placeholders, secrets, the demo logins, CORS, rate limits, the public URL, and running the worker on its own.