hivelab 0.2.0

Command-line tool for pushing structured Markdown research notes to any hivelab-compatible backend.

hivelab

Command-line tool for pushing structured Markdown research notes to any hivelab-compatible backend.

hivelab is generic — it doesn't care what you're researching (ML, wet lab, journalism, anything). It speaks one protocol: POST /api/v1/experiments with a Markdown body, an optional template name, and optional thread name. The backend is responsible for parsing/extracting/storing.

Reference backend: hive-lab. Any server that implements the same /api/v1/* endpoints works.

Install

pip install hivelab        # PyPI (when published)
# or, from source:
pip install -e /path/to/hivelab

Two entrypoints: hivelab and the short alias hl.

Quick start

# 1. Save your backend URL + token
hivelab login
#   Backend URL [http://localhost:3000]: …
#   API token (lab_…): ************
#   ✓ 已保存 profile default, 登录身份：Bob (bob) @ http://localhost:3000

# 2. See what you have access to
hivelab projects
hivelab templates concordia

# 3. Push a single .md file
hivelab push ./run-42.md --project concordia --template "ML 训练"

# 4. Push a whole run directory (auto-picks summary.md / notes.md / README.md,
#    attaches config.json / metrics.json so the LLM can extract fields from them)
hivelab push ./runs/exp-042/ --project concordia --template "ML 训练"

# 5. Drop a quick idea
hivelab note "明天试试在 P2 任务上加个 MoE 路由器" --project concordia

# 6. Check this week's digest
hivelab digest --week current

Commands

# Auth / context
hivelab login [--url URL] [--token TOKEN] [--name PROFILE] [--set-default]
hivelab logout [--name PROFILE]
hivelab profiles                          # list all configured backends
hivelab whoami                            # check who you're logged in as
hivelab projects                          # list projects
hivelab templates <project>               # show templates + threads for a project

# Push content
hivelab push <path> --project X [--template Y] [--thread Z]
                    [--title T] [--field name=value]... [--publish | --draft]
                    [--no-llm] [--dry-run]
hivelab note "text..." --project X [--title T]

# Todos
hivelab todo list [--scope me|project] [-P slug] [--status open|done|all]
hivelab todo add "title" -P slug [--assign username] [--due YYYY-MM-DD] [--thread id] [--desc "..."]
hivelab todo done <id_or_prefix>          # mark complete
hivelab todo reopen <id_or_prefix>
hivelab todo drop <id_or_prefix>

# Read / search
hivelab search "query"                    # cross-search experiments/notes/todos/threads
hivelab digest [--week current|previous|YYYY-MM-DD] [--json]
hivelab notif [--all] [--read]

Use hivelab <cmd> --help for full per-command help.

push modes

Mode	When	Behavior
LLM-extracted (default)	--template T given, no --field overrides	Backend runs Claude to extract fields from the Markdown. Saves as draft for web review.
Direct (bypass LLM)	--field key=value overrides	Listed fields go straight in, no LLM call for them. Combine with --no-llm to skip LLM entirely. Default status is published.
Note (no template)	use hivelab note instead	Plain Markdown, no structured fields, always published.

Field overrides

If your training script already knows the numbers, pass them directly — no need to round-trip through the LLM:

hivelab push ./run/notes.md \
  --project concordia --template "ML 训练" --thread "P1 ablation" \
  --field model=llama-3-8b \
  --field lr=5e-4 \
  --field seed=42 \
  --field metric_acc=87.3 \
  --publish

Booleans and numbers are auto-coerced (true/false, 0.001, 42); everything else is treated as a string.

Profiles (multi-backend)

Most users only need one backend; the default profile is just called default. For multiple backends:

hivelab login --name local --url http://localhost:3000 --token lab_xxx --set-default
hivelab login --name prod  --url https://research.example.com --token lab_yyy

hivelab projects                 # uses default profile
hivelab -p prod projects         # uses 'prod' profile

Environment variable override (useful in CI):

HIVELAB_URL=https://research.example.com HIVELAB_TOKEN=lab_xxx hivelab push ...

Config file location: ~/.config/hivelab/config.json (mode 0600).

In Python scripts (no shell)

There's no Python SDK yet — that's a v2 candidate. For now, call the protocol directly:

import requests

requests.post(
    "http://localhost:3000/api/v1/experiments",
    headers={"Authorization": f"Bearer {token}"},
    json={
        "project": "concordia",
        "template": "ML 训练",
        "thread": "P1 ablation",
        "title": f"lr={lr}, seed={seed}",
        "markdown": notebook_summary,
        "structuredFields": {
            "model": {"value": "llama-3-8b", "confidence": 1, "edited": True},
            "lr": {"value": lr, "confidence": 1, "edited": True},
            "seed": {"value": seed, "confidence": 1, "edited": True},
            "metric_acc": {"value": acc, "confidence": 1, "edited": True},
        },
        "status": "published",
    },
).raise_for_status()

License

MIT.