# VeriThink Assistant — guide for users and builders

Two levels: **Part 1** — for the end user (doctor, lawyer — anyone using a ready-made assistant), **Part 2** — for the builder (founder, integrator — anyone assembling an assistant for their niche). Apps (Windows / Android / iPhone) — [APPS.md](../APPS.md) (RU).

---

## Part 1. Using a ready-made assistant (example: doctor)

### First launch

1. Open `http://{server-address}:8787/assistant.html` in a browser (on phone — same URL; then “Add to Home Screen” for an app-like icon).
2. **⚙ Settings** tab:
   - **Base URL** — pre-filled (server address);
   - **API key** — paste if the server issued one (for local home install you can leave empty);
   - **Tenant** — your “data space”; records and files are visible only inside it. Pick your own id, e.g. `dr-ivanova`;
   - **Template** — choose an assistant (e.g. “Doctor assistant”) → **Save**.

### Daily workflow

- **📋 Records** → “+ Create” — new patient card (name, history, complaints, allergies, medications). Inside the card — visits (date, complaints, notes).
- **Files** on the card — photograph a lab form or screenshot a chat from the phone camera. Text is recognized automatically in a few seconds (status “Ready”). If OCR is unavailable — open the file and type text manually; it still enters the knowledge base.
- **Analysis buttons** on the card:
  - “Lab breakdown” (on file page) — indicator table: normal / high / low, what to clarify;
  - “Trend over time” — compare labs by date;
  - “Lifestyle and nutrition recommendations”;
  - “Full patient review” (⏳ marked deep) — full engine reasoning: patterns, hypotheses to check, workup plan. Takes minutes and costs more — run deliberately.
  - Each result is saved on the card (history is kept) and ends with a disclaimer: decision support for the physician, not a diagnosis.
- **💬 Chat** — free-form questions (“what is the patient’s ferritin?”); the assistant answers from uploaded documents. Mode selector: quick — seconds/cents, standard — more accurate, deep — full reasoning (minutes).
- **Cost:** after each run the price is shown (~cents for a normal run). In Settings — “Reasoning provider”: *auto (hybrid)* — deep runs via your browser ChatGPT account ($0 extra beyond subscription), rest via cheap API.

### Privacy

Patient data lives in your tenant on your server (local install — only on your machine). Delete all tenant data via admin (`/v1/gdpr/delete`).

---

## Part 2. Building your own assistant (example: astrologer)

An assistant = **one JSON file**, no programming. The platform provides: cards with your fields, photo → text, knowledge base, chat, and “analyses” at any depth.

### Step 1. Create a pack

File `packs/astrology/pack.json` on the server (directory from `VERITHINK_PACKS_DIR`, default `{repo}/packs`):

```json
{
  "id": "astrology",
  "title": "Astrologer assistant",
  "disclaimer": "Entertainment and consultation service. Not a prediction or instruction to act.",
  "recordTypes": [
    { "id": "client", "title": "Client", "parent": null,
      "fields": [
        { "id": "name", "title": "Name", "type": "text", "required": true },
        { "id": "birthDate", "title": "Birth date", "type": "date", "required": true },
        { "id": "birthTime", "title": "Birth time", "type": "text" },
        { "id": "birthPlace", "title": "Birth place", "type": "text" },
        { "id": "request", "title": "Client request", "type": "multiline" }
      ] },
    { "id": "session", "title": "Consultation", "parent": "client",
      "fields": [
        { "id": "date", "title": "Date", "type": "date" },
        { "id": "notes", "title": "Notes", "type": "multiline" }
      ] }
  ],
  "playbooks": [
    { "id": "natal-brief", "title": "Express portrait", "mode": "standard", "scope": "record",
      "prompt": "You are an experienced consulting astrologer. From client data write a structured portrait: strengths, growth areas, topics for the session. Write respectfully without categorical predictions.\n{input}" },
    { "id": "full-natal", "title": "Full natal chart reading", "mode": "deep", "scope": "record",
      "prompt": "Deep reading for a professional astrologer: client chart, key configurations, interpretations by schools, questions to clarify with the client, session plan.\n{input}" }
  ]
}
```

Rules:

- `recordTypes` — your entities; `parent` links child to parent (client → sessions). Field types: `text`, `date`, `multiline`.
- `playbooks` — analysis buttons. `scope: "record"` — input = whole card (fields + child records + OCR text of all files); `scope: "file"` — one document. `mode`: `quick` (cheap, 1 call), `standard` (more accurate, 1 call), `deep` (full engine pipeline, expensive/slow). `{input}` in the prompt is replaced with card data.
- `disclaimer` is appended to every result automatically.

### Step 2. Restart ReasonService

The pack is loaded, appears in `GET /v1/packs` and in the “Template” selector on `/assistant.html`. UI builds from your schema: lists, forms, analysis buttons.

### Step 3. Give users access

- Each user — own **tenant** (data isolation) and, for paid access, an API key (see [BILLING.md](BILLING.md), [ADMIN.md](../ADMIN.md) RU).
- Apps: Windows shortcut (`SymFSM.Studio.exe --assistant`), Android/RuStore via TWA, iPhone via PWA — step by step in [APPS.md](../APPS.md) (RU).
- Integrations (Telegram bot, n8n, any OpenAI client) — [BUSINESS_INTEGRATIONS.md](../BUSINESS_INTEGRATIONS.md) (RU); general KB — `/v1/kb/*` ([API.md](API.md)).

### Economics (important)

- quick/standard runs — one LLM call (cents on gpt-4.1-mini class models).
- Deep — full reasoning pipeline; in hybrid mode (`VERITHINK_LLM_PROVIDER=hybrid`) it routes through the user’s browser account (ChatGPT Plus) and does not generate token billing. Routing rules — `VERITHINK_HYBRID_RULES`.
- Photo OCR — one cheap vision call per file, cached (re-OCR of the same file is not billed).

### What packs cannot do yet (honest list)

- Custom field types (validated numbers, picklists) — only text/date/multiline.
- Custom UI look — one interface for all; branding is white-label backlog.
- Pack wizard in admin — backlog (Phase D); for now write JSON by hand using this guide.