Metadata-Version: 2.4
Name: hivelab
Version: 0.2.0
Summary: Command-line tool for pushing structured Markdown research notes to any hivelab-compatible backend.
Author: hivelab
License: MIT
Keywords: cli,experiment-tracking,markdown,notes,research
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.9
Requires-Dist: click>=8.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: requests>=2.31
Requires-Dist: rich>=13.7
Description-Content-Type: text/markdown

# 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](../hive-lab/). Any server that implements the same `/api/v1/*` endpoints works.

## Install

```bash
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

```bash
# 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:

```bash
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:

```bash
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):

```bash
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:

```python
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.
