Metadata-Version: 2.5
Name: plesty-hub-agents
Version: 0.1.0
Summary: Harness-agnostic agentic framework for developing and maintaining PLESTY hub modules.
Author-email: Yunshuang Yuan <yuanyunshuang@gmail.com>
License-Expression: LGPL-3.0-or-later
License-File: LICENSE
License-File: LICENSES/LGPL-3.0-or-later.txt
Requires-Python: >=3.12
Requires-Dist: packaging<27,>=24
Requires-Dist: pyyaml<7,>=6.0
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.2; extra == 'mcp'
Description-Content-Type: text/markdown

# plesty-hub-agents

Skills and agent roles for building PLESTY lab experiments and the hub modules behind them —
device drivers, analyzers and experiments — with the coding agent you already use.

Tell it which instruments you have and what you want to measure. It writes the device servers,
field-tests them on your hardware until they pass, builds the experiment, runs it with you on
the bench, and then improves it run by run — asking you before every step that touches the
hardware and before every new round.

## Install

### Claude Code — as a plugin (recommended)

```
/plugin marketplace add https://gitlab.com/plesty/ai/plesty-hub-agents.git
/plugin install plesty-hub-agents@plesty
```

The skills appear as `/plesty-hub-agents:hub-experiment`, `/plesty-hub-agents:hub-comply`, … and
the roles as subagents. `/plugin update` brings in each release. For the MCP tools
(`plesty check`, GitLab and PyPI look-ups) also install the CLI:

```bash
uv tool install "plesty-hub-agents[mcp] @ git+https://gitlab.com/plesty/ai/plesty-hub-agents"
hub-agents doctor        # uv, git, glab, Python — installs what it can, never with sudo
```

### Claude app (claude.ai, Claude Desktop) — as skills

Zip a skill folder and upload it under **Settings → Capabilities → Skills**:

```bash
git clone https://gitlab.com/plesty/ai/plesty-hub-agents.git && cd plesty-hub-agents/skills
zip -r hub-experiment.zip hub-experiment
```

The app has no access to your lab network or your checkouts, so use it for the stages that are
conversation and analysis — requirements, the plan, reading a finished run and proposing the
next round. Building, field-testing and running happen in Claude Code (see
[the experiment guide](docs/experiment.md)).

### Codex CLI, Gemini CLI — through the CLI

```bash
hub-agents workspace init ~/plesty-hub    # one directory for all modules; projects every harness on PATH
cd ~/plesty-hub && codex                  # or gemini — or claude, if you do not use the plugin
```

## Build an experiment

```
/plesty-hub-agents:hub-experiment pow-pl
```

| Stage | What happens | You |
|---|---|---|
| 1 Requirements | Q&A: each device (model, role, bench, connection, manual, safety limits), then the experiment (plan, records, in-run decisions, success) | answer, confirm |
| 2 Plan | what each device module and the experiment need, what runs in parallel, the risks | approve |
| 3 Devices | one agent per device, in parallel; then the hardware set-up and a field-test loop — find the cause, fix, test again — until each device passes | connect the hardware, say when it is free to act |
| 4 Experiment | the experiment module, a dry run and a full run against the device simulators | review the MR |
| 5 Run | you run it from the bench console with the agent monitoring, or the agent runs it | pick one |
| 6 Refine | efficiency, parameters, in-run decisions, data quality, robustness — a proposal for the next round | approve each round |

The pipeline keeps its state in `.hub-agents/experiments/<slug>/`, so it resumes where it
stopped. That folder holds bench addresses and lab notes and is never committed.

## What ships

| Skill | Does |
|---|---|
| `hub-experiment` | instruments to a successful, improving experiment — the six stages above |
| `hub-module` | a new device module: architect → engineer → publisher |
| `hub-field-test` | configure a device's field test, or run it on the hardware |
| `hub-comply` | `plesty check` → triage → fix → repeat until every gate passes |
| `hub-develop` | branch off the right line → implement → comply → commit → MR |
| `hub-docs` | audit a module's `docs/` against its code and fix it |
| `hub-publish` | release merge, tag, CI, PyPI, merge back |
| `hub-workspace` | clone / status / update checkouts by name, path or group |

Roles `hub-architect` → `hub-engineer` → `hub-publisher` hand off through
`.hub-agents/handoff/*.md`. Branch guards stop an edit or a push on `main`, `exp` or a
`maintain/*` line. Skills are validated for plesty-lib `>=0.6.0,<0.7` and plesty-sdk
`>=0.5.0,<0.6`; a module pinned outside that range is told so.

## Documentation

- [Build an experiment](docs/experiment.md) — the pipeline, in Claude Code and in the Claude app
- [Using the framework](docs/usage.md) — install, workspace, every skill, the module pipeline, MCP, headless use
- [Architecture](docs/architecture.md) — how one set of skills serves every harness

## Develop

```bash
uv sync --all-extras
uv run pytest            # catalog, plugin manifests, contracts against the installed lib/sdk
uv run plesty check      # quantum, every gate
```

Changes land through a merge request into `exp`; `main` moves only by release.

## License

LGPL-3.0-or-later, see [LICENSE](LICENSE).
