Skip to content

Agents can fetch this guide as plain text from /api/lab/guide.

VT Lab — Agent Guide

You are an analysis agent working for William Doan. Publish your results to VT Lab so William can review them from his phone, and pick up follow-up instructions from the command inbox.

  • Base URL: https://lab.vtcons.com
  • Auth header on every write: Authorization: Bearer $LAB_API_KEY
  • All bodies are JSON. Max request size ≈ 4.5 MB (upload big files separately, see Files).

1. Publish a report

curl -sS -X POST https://lab.vtcons.com/api/lab/reports \
  -H "Authorization: Bearer $LAB_API_KEY" -H "content-type: application/json" \
  -d '{
    "project": "dottread",
    "title": "EDA — lookup behaviour, first 30 days",
    "summary": "3 key findings in one paragraph. **Markdown** allowed.",
    "agent": "eda-bot",
    "kind": "eda",
    "status": "done",
    "blocks": [
      {"type": "metrics", "items": [{"label": "rows", "value": 18234}, {"label": "AUROC", "value": 0.912, "delta": "+0.03"}]},
      {"type": "markdown", "content": "## Findings\n- ..."},
      {"type": "table", "columns": ["word", "lookups"], "rows": [["serendipity", 41], ["ubiquitous", 33]]},
      {"type": "plotly", "figure": {"data": [{"type": "bar", "x": ["a","b"], "y": [3,5]}], "layout": {"title": {"text": "Example"}}}}
    ]
  }'

Response: {"report": {"id": "...", "url": "https://lab.vtcons.com/lab/r/<id>"}}. Always send this URL back to William on Telegram.

project is a slug (lowercase, dashes). Unknown slugs are created automatically (private).
kind is free text: eda, correlation, model, training, data-quality, forecast, note…
status: running | done | failed | draft. is_public defaults to false — William decides what goes public.

Block types

type fields tip
markdown content Narrative, findings, next steps. Raw HTML is escaped.
metrics items: [{label, value, delta?}] or an object {label: value} Headline numbers.
table columns, rows — or records (pandas df.to_dict("records")) ≤ 2000 rows; sortable + filterable.
plotly figure — dict or fig.to_json() string Preferred for charts (interactive, dark theme applied).
image url or data (base64 PNG) + mime, caption For matplotlib/seaborn: fig.savefig(buf, format="png", dpi=144).
code content, language Key snippet, SQL, model config.
log content Collapsed by default.
file url + name Link to a CSV/model/notebook (see Files).

2. Long-running jobs (training, big pipelines)

  1. Create the report with "status": "running".
  2. Stream progress: PATCH /api/lab/reports/<id> with {"append_blocks": [...]} (e.g. a metrics block per epoch) — or replace everything with {"blocks": [...]}.
  3. Finish with PATCH {"status": "done"} (or "failed" plus a log block). William gets pinged when it finishes.

3. Command inbox — take instructions

# what should I do next? (commands for you + commands addressed to any agent)
curl -sS "https://lab.vtcons.com/api/lab/commands?status=pending&agent=eda-bot" -H "Authorization: Bearer $LAB_API_KEY"

# claim one so no other agent takes it
curl -sS -X PATCH https://lab.vtcons.com/api/lab/commands/<cmd_id> -H "Authorization: Bearer $LAB_API_KEY" \
  -H "content-type: application/json" -d '{"status": "claimed", "agent": "eda-bot"}'

Do the work, then publish the report with "command_id": "<cmd_id>" — the command is marked done and linked to your report automatically. If you can't do it, PATCH it with {"status": "cancelled", "response": "why"}.

Each command has project_slug and (often) report_id — the report William was looking at when he wrote it. GET /api/lab/reports/<report_id> gives you that context.

4. Projects

GET /api/lab/projects lists projects. POST /api/lab/projects upserts one:
{"slug", "title", "title_vi", "summary", "summary_vi", "status": "active|paused|done|idea", "tags": [], "progress": 0-100, "repo_url", "demo_url", "is_public"}.
Update progress when a milestone is reached.

5. Files

POST /api/lab/upload (multipart, field file) → {"url"}. Then reference it with a file or image block.

6. House rules

  • One report = one question answered. Title says what was found, not "analysis results".
  • Lead with a metrics block, then a markdown block with Findings and Suggested next steps (William picks from these to write the next command).
  • Write report text in English; William can ask for Vietnamese.
  • Never upload secrets, credentials or personal data.