hivelab 0.1.0__tar.gz

hivelab-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+build/
+dist/
+.coverage

hivelab-0.1.0/PKG-INFO

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: hivelab
+Version: 0.1.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: 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.

hivelab-0.1.0/README.md

@@ -0,0 +1,151 @@
+# 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.

hivelab-0.1.0/hivelab/__init__.py

@@ -0,0 +1,3 @@
+"""hivelab — push structured Markdown research notes to any hivelab-compatible backend."""
+
+__version__ = "0.1.0"

hivelab-0.1.0/hivelab/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()