guap-lab-auto 0.1.0__tar.gz

guap_lab_auto-0.1.0/.agents/skills/guap-lab-workflow/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: guap-lab-workflow
+description: Sync GUAP student lab tasks with lab-auto, edit reports in local folders, mark REVIEW, convert DOCX to PDF, and submit only after explicit human approval.
+version: 1.0.0
+platforms: [macos, linux, windows]
+metadata: {"openclaw":{"emoji":"🎓","homepage":"https://github.com/your-org/lab_automation","requires":{"bins":["lab-auto"]}},"hermes":{"emoji":"🎓","tags":["guap","education","labs","cli"],"category":"education","requires_toolsets":["terminal"]}}
+---
+
+# GUAP lab workflow (`lab-auto`)
+
+Use this skill when the user works on **GUAP** (`pro.guap.ru`) student lab tasks via the **`lab-auto`** CLI (PyPI package `guap-lab-auto`).
+
+> Unofficial tool — not affiliated with GUAP. Portal HTML changes can break parsers.
+
+## When to use
+
+- Sync tasks from the GUAP website into local folders
+- Write or update lab reports in the workspace
+- Mark work ready for human review (`[REVIEW]`)
+- Convert DOCX → PDF and submit PDFs **only when the user explicitly requests submission**
+
+## Prerequisites
+
+```bash
+pip install guap-lab-auto
+playwright install chromium
+lab-auto workspace set /path/to/workspace
+lab-auto auth login    # human completes browser login
+```
+
+Optional: LibreOffice (`soffice`) or Microsoft Word (Windows) for `lab-auto convert`.
+
+Environment overrides: `LAB_AUTO_ROOT`, `LAB_AUTO_SESSION_KEY` (advanced).
+
+## Source of truth (read first)
+
+| Path | Purpose |
+|------|---------|
+| `{workspace}/state/works.yaml` | Canonical records (`work_id`, statuses) |
+| `{workspace}/state/summary.md` | Overview by subject |
+| `{workspace}/state/needs_review.md` | Tasks in `[REVIEW]` |
+| `{workspace}/labs/<subject>/...` | Per-task folders |
+| `{workspace}/logs/[AI] YYYY-MM-DD.md` | Short action log |
+
+**IDs:** CLI uses `work_id` like `task-178541`; folders look like `[STATUS] Task title [178541]`.
+
+Skip `archived: true` unless the user asks about archived work.
+
+## Standard procedure
+
+1. `lab-auto sync` — refresh from website (do not run parallel with `submit` on the same task)
+2. Edit report files inside the task folder under `labs/`
+3. `lab-auto review <work-id>` — after AI or user edits the report
+4. `lab-auto convert <work-id> --docx report.docx` — if the deliverable is DOCX
+5. `lab-auto submit <work-id> --file report.pdf` — **only if the user clearly asked to submit**
+6. `lab-auto sync` — reconcile status
+
+## Commands (terminal)
+
+Use the **terminal** toolset / shell. All commands accept `work-id` (`task-178541`), folder name, or relative folder path.
+
+```bash
+lab-auto auth login | check | migrate-session | logout
+lab-auto workspace set | show | unset <path>
+lab-auto sync [--archive]
+lab-auto status [--all]
+lab-auto review <work-id>
+lab-auto convert <work-id> --docx file.docx [--output file.pdf]
+lab-auto submit <work-id> --file file.pdf
+lab-auto archive | unarchive <work-id>
+```
+
+One-shot workspace: `lab-auto --root /path/to/workspace sync`
+
+## Status prefixes
+
+| Prefix | Meaning |
+|--------|---------|
+| `[REFACTOR]` | Not accepted on website |
+| `[REVIEW]` | Local — ready for human review |
+| `[SENT]` | Submitted, awaiting teacher |
+| `[SENTFAILED]` | Upload failed — suggest `sync` |
+| `[DONE]` | Accepted |
+| `[UNKNOWN]` | Unrecognized website status |
+
+`[REVIEW]`, `[SENT]`, and `[SENTFAILED]` stay sticky until the website shows `ожидает проверки` or `принят`.
+
+## Hard rules
+
+1. **Never** run `submit` without explicit user approval after review.
+2. **Never** scrape credentials or bypass `lab-auto auth login`.
+3. **Never** delete `state/works.yaml` or session files to “fix” issues.
+4. If `sync` parses **0 tasks**, suggest `lab-auto auth check` — state is unchanged.
+5. Log only brief success/failure lines to `logs/[AI] YYYY-MM-DD.md`.
+
+## Pitfalls
+
+- **Session:** encrypted at `session/storage_state.json`; key in user config dir. Use `lab-auto auth migrate-session` for legacy files.
+- **Submit lag:** detail page may lag → `[SENTFAILED]`; run `lab-auto sync`.
+- **Concurrency:** avoid `sync` + `submit` on the same task simultaneously.
+
+## Verification
+
+- `lab-auto status` shows expected prefix and `work_id`
+- Folder name matches `[STATUS] … [site-id]`
+- After submit + sync, website status aligns with `[SENT]` or `[DONE]`
+
+## More detail
+
+- Repo agent guide: `AGENTS.md`
+- Command reference: `{baseDir}/references/commands.md`
+- OpenClaw setup: `{baseDir}/references/openclaw.md`
+- Hermes setup: `{baseDir}/references/hermes.md`

guap_lab_auto-0.1.0/.agents/skills/guap-lab-workflow/references/commands.md

@@ -0,0 +1,39 @@
+# lab-auto command reference
+
+Install: `pip install guap-lab-auto` · CLI: `lab-auto` · Python 3.11+
+
+## Auth
+
+| Command | Description |
+|---------|-------------|
+| `lab-auto auth login` | Interactive GUAP login (stores encrypted session) |
+| `lab-auto auth check` | Validate session; may upgrade encryption |
+| `lab-auto auth migrate-session` | Encrypt legacy session without browser |
+| `lab-auto auth import-cookie <file.json>` | Import Playwright storage or cookie list |
+| `lab-auto auth logout` | Delete workspace session file |
+
+## Workspace
+
+| Command | Description |
+|---------|-------------|
+| `lab-auto workspace set <path>` | Save default workspace |
+| `lab-auto workspace show` | Show active + saved paths |
+| `lab-auto workspace unset` | Clear saved default |
+
+Override: `--root <path>` or `LAB_AUTO_ROOT=<path>`
+
+## Workflow
+
+| Command | Description |
+|---------|-------------|
+| `lab-auto sync` | Sync tasks from GUAP |
+| `lab-auto sync --archive` | Keep removed tasks as archived |
+| `lab-auto status` | List active works |
+| `lab-auto status --all` | Include archived |
+| `lab-auto review <ref>` | Mark `[REVIEW]` and rename folder |
+| `lab-auto convert <ref> --docx f.docx` | DOCX → PDF in work folder |
+| `lab-auto submit <ref> --file f.pdf` | Upload PDF (after user approval) |
+| `lab-auto archive <ref>` | Archive work |
+| `lab-auto unarchive <ref>` | Restore archived work |
+
+`<ref>` = `task-178541`, folder name, or path under workspace.

guap_lab_auto-0.1.0/.agents/skills/guap-lab-workflow/references/hermes.md

@@ -0,0 +1,87 @@
+# Hermes Agent integration
+
+[Hermes Agent](https://hermes-agent.nousresearch.com/) uses AgentSkills-compatible `SKILL.md` files under `~/.hermes/skills/`.
+
+## Install the skill
+
+### Option A — Install script (recommended)
+
+From the repo root:
+
+```bash
+# Linux / macOS
+./scripts/install-agent-skills.sh
+
+# Windows PowerShell
+.\scripts\install-agent-skills.ps1
+```
+
+Copies `skills/guap-lab-workflow/` → `~/.hermes/skills/guap-lab-workflow/`.
+
+### Option B — Manual copy
+
+```bash
+cp -r skills/guap-lab-workflow ~/.hermes/skills/guap-lab-workflow
+```
+
+### Option C — External skill directory (no copy)
+
+Add the repo `skills/` folder to `~/.hermes/config.yaml`:
+
+```yaml
+skills:
+  external_dirs:
+    - /path/to/lab_automation/skills
+```
+
+Local `~/.hermes/skills/guap-lab-workflow` wins if the same name exists in both places.
+
+## Use in Hermes
+
+```bash
+# Slash command
+/guap-lab-workflow sync my labs and list tasks in REVIEW
+
+# Preload skill + terminal tools
+hermes chat --toolsets terminal,skills -s guap-lab-workflow -q "Run lab-auto status in my workspace"
+
+# TUI
+hermes --tui
+```
+
+## Config
+
+Set the default workspace for subprocesses in `~/.hermes/.env` or shell profile:
+
+```bash
+export LAB_AUTO_ROOT=/path/to/your/guap-workspace
+```
+
+Or pass per command:
+
+```bash
+lab-auto --root /path/to/workspace sync
+```
+
+## Requirements
+
+- Skill metadata: `requires_toolsets: [terminal]` — enable **terminal** in the session.
+- Binaries: `lab-auto` on PATH (`pip install guap-lab-auto`).
+- Run `playwright install chromium` once on the machine.
+- `lab-auto auth login` must be completed by the user (browser).
+
+## Bundles (optional)
+
+Group with other dev skills:
+
+```bash
+hermes bundles create guap-labs \
+  --skill guap-lab-workflow \
+  -d "GUAP lab sync and report workflow"
+```
+
+Then: `/guap-labs help me finish lab 3`
+
+## Human-in-the-loop
+
+Hermes must **not** run `lab-auto submit` unless the user explicitly approves submission.

guap_lab_auto-0.1.0/.agents/skills/guap-lab-workflow/references/openclaw.md

@@ -0,0 +1,72 @@
+# OpenClaw integration
+
+[OpenClaw](https://documentation.openclaw.ai/) loads [AgentSkills](https://agentskills.io/) folders with `SKILL.md`.
+
+## Option A — This repo as the agent workspace
+
+Clone the repo and use it as the OpenClaw workspace. Skills load from:
+
+| Precedence | Path in repo |
+|------------|----------------|
+| Workspace | `skills/guap-lab-workflow/` |
+| Project agent | `.agents/skills/guap-lab-workflow/` |
+
+Enable in `openclaw.json`:
+
+```json5
+{
+  agents: {
+    defaults: {
+      skills: ["guap-lab-workflow"],
+    },
+  },
+  skills: {
+    entries: {
+      "guap-lab-workflow": {
+        enabled: true,
+        env: {
+          LAB_AUTO_ROOT: "/path/to/your/guap-workspace",
+        },
+      },
+    },
+  },
+}
+```
+
+Slash command: `/guap-lab-workflow` (when `user-invocable` is enabled in frontmatter).
+
+## Option B — Install for all local agents
+
+```bash
+openclaw skills install /path/to/lab_automation/skills/guap-lab-workflow --global
+# or from ClawHub when published
+```
+
+## Option C — Extra skill directory
+
+```json5
+{
+  skills: {
+    load: {
+      extraDirs: ["/path/to/lab_automation/skills"],
+    },
+  },
+}
+```
+
+## Requirements (gating)
+
+The skill declares `metadata.openclaw.requires.bins: ["lab-auto"]`. Install the CLI before enabling:
+
+```bash
+pip install guap-lab-auto
+playwright install chromium
+```
+
+## Terminal tools
+
+The agent needs shell access to run `lab-auto`. Enable your OpenClaw agent’s terminal/exec toolset alongside this skill.
+
+## Human-in-the-loop
+
+OpenClaw must **not** auto-run `lab-auto submit` unless the user explicitly requests it in the same conversation.

guap_lab_auto-0.1.0/AGENTS.md

@@ -0,0 +1,187 @@
+# 🤖 Agent guide — guap-lab-auto
+
+Instructions for coding agents (Cursor, Claude, Copilot, **OpenClaw**, **Hermes**, etc.) working with this repository or the installed `lab-auto` CLI.
+
+---
+
+## What this project is
+
+- **Package name (PyPI):** `guap-lab-auto`
+- **CLI command:** `lab-auto`
+- **Purpose:** Sync GUAP student tasks from `https://pro.guap.ru`, mirror them into local folders, track status in YAML, and submit PDF reports after explicit human approval.
+- **Not official:** GUAP can change HTML anytime; parsers may break.
+
+---
+
+## Install (agent environment)
+
+### From PyPI
+
+```bash
+pip install guap-lab-auto
+playwright install chromium
+```
+
+### From this repo
+
+```bash
+pip install -e ".[dev]"
+playwright install chromium
+```
+
+### Requirements
+
+- Python **3.11+**
+- **Chromium** for Playwright (`playwright install chromium`)
+- Network access to `pro.guap.ru` for sync/submit/auth
+- Optional: **LibreOffice** (`soffice`) or **Microsoft Word** (Windows) for `lab-auto convert`
+
+---
+
+## Workspace setup
+
+1. Choose a directory for all user data (not the git clone root unless intended).
+2. Run:
+
+```bash
+lab-auto workspace set /path/to/workspace
+lab-auto auth login    # human must complete browser login
+lab-auto auth check
+lab-auto sync
+```
+
+Override for one command: `lab-auto --root /path/to/workspace sync` or env `LAB_AUTO_ROOT`.
+
+---
+
+## Source of truth (read first)
+
+| File | Use |
+|------|-----|
+| `state/works.yaml` | Canonical task records (`work_id`, statuses, paths) |
+| `state/summary.md` | Human-readable overview by subject |
+| `state/needs_review.md` | Tasks in `[REVIEW]` |
+| `labs/<subject>/...` | Per-task folders (reports, `task.pdf`) |
+| `logs/[AI] YYYY-MM-DD.md` | Append short action notes |
+
+**Skip** `archived: true` rows unless the user asks about archived work.
+
+**IDs**
+
+- CLI / YAML: `work_id` → `task-178541` (from task URL)
+- `task_site_id` → `178541`
+- Folder name: `[STATUS] Task title [178541]`
+
+---
+
+## Standard workflow (do not skip review)
+
+```text
+sync → write report in work folder → review → convert (if DOCX) → submit (only if user asked) → sync
+```
+
+| Step | Command | Agent notes |
+|------|---------|-------------|
+| 1 | `lab-auto sync` | Refresh from website; do not run parallel with `submit` on same task |
+| 2 | Edit files in `labs/.../` | Keep artifacts inside the work folder |
+| 3 | `lab-auto review <work-id>` | Required after AI changes report |
+| 4 | `lab-auto convert <id> --docx report.docx` | Only if user has DOCX |
+| 5 | `lab-auto submit <id> --file report.pdf` | **Only when user explicitly requests submission** |
+| 6 | `lab-auto sync` | Reconcile status |
+
+---
+
+## Hard rules for agents
+
+1. **Never run `submit`** unless the user clearly said the report is reviewed and should be uploaded.
+2. **Never automate GUAP login** beyond documented CLI commands (no credential scraping).
+3. **Do not delete** `state/works.yaml` or session files to “fix” issues — use `auth login`, `sync`, or documented repair.
+4. **Prefer CLI** over reimplementing browser/parsing logic in ad-hoc scripts.
+5. **Log briefly** to `logs/[AI] YYYY-MM-DD.md` on success/failure (no verbose step spam).
+6. If `sync` reports **0 tasks**, treat as auth/markup problem — suggest `auth check` or `auth login`; state is left unchanged.
+7. **Archived works** are frozen until `lab-auto unarchive <id>`.
+
+---
+
+## Command quick reference
+
+```bash
+lab-auto auth login | check | migrate-session | logout
+lab-auto workspace set | show | unset
+lab-auto sync [--archive]
+lab-auto status [--all]
+lab-auto review <work-id-or-folder>
+lab-auto convert <work-id-or-folder> --docx file.docx [--output file.pdf]
+lab-auto submit <work-id-or-folder> --file file.pdf
+lab-auto archive | unarchive <work-id-or-folder>
+```
+
+`work-id-or-folder` can be `task-178541`, folder name, or relative folder path under the workspace.
+
+---
+
+## Status semantics (for merge/sync)
+
+- `[REVIEW]`, `[SENT]`, `[SENTFAILED]` are **sticky** until the website shows `ожидает проверки` or `принят`.
+- `[DONE]` is not downgraded to `[REFACTOR]` on a lagging list; resubmit → site `ожидает проверки` → local `[SENT]`.
+- `[SENTFAILED]` after submit: suggest `lab-auto sync` to reconcile.
+
+---
+
+## Development (agents modifying this repo)
+
+```bash
+pip install -e ".[dev]"
+pytest                    # unit + fixture tests (no network)
+pytest -m live            # needs LAB_AUTO_ROOT + valid session
+```
+
+Layout:
+
+```text
+src/lab_auto/     # CLI and services
+tests/fixtures/   # captured GUAP HTML
+skills/           # optional Cursor skill for lab workflow
+```
+
+Key modules: `sync.py`, `submit.py`, `parsers.py`, `state.py`, `paths.py`, `session_store.py`, `browser.py`.
+
+When changing parsers, update fixtures via `scripts/capture_guap_fixtures.py` after a real login.
+
+---
+
+## OpenClaw
+
+1. Install skill: `./scripts/install-agent-skills.sh` or use this repo as workspace (`skills/` + `.agents/skills/`).
+2. Enable in `~/.openclaw/openclaw.json` — see `examples/openclaw.json.example`.
+3. Set `LAB_AUTO_ROOT` under `skills.entries.guap-lab-workflow.env`.
+4. Enable **terminal/shell** tools for the agent.
+5. Invoke: `/guap-lab-workflow <request>`.
+
+Details: [docs/integrations/openclaw.md](docs/integrations/openclaw.md)
+
+## Hermes Agent
+
+1. Install skill: `./scripts/install-agent-skills.sh` → `~/.hermes/skills/guap-lab-workflow/`.
+2. Or add `skills.external_dirs` — see `examples/hermes-skills.example.yaml`.
+3. Set `LAB_AUTO_ROOT` in `~/.hermes/.env`.
+4. Run with terminal: `hermes chat --toolsets terminal,skills -s guap-lab-workflow`.
+5. Invoke: `/guap-lab-workflow <request>`.
+
+Details: [docs/integrations/hermes.md](docs/integrations/hermes.md)
+
+## AgentSkills skill (canonical)
+
+| Path | Role |
+|------|------|
+| `skills/guap-lab-workflow/SKILL.md` | Main skill (edit here) |
+| `skills/guap-lab-workflow/references/` | Command + integration refs |
+| `.agents/skills/guap-lab-workflow/` | OpenClaw project-agent copy (re-sync via install script) |
+
+After editing the skill, run `scripts/install-agent-skills.sh` to update `~/.hermes/skills` and `~/.openclaw/skills`.
+
+---
+
+## Publishing reminder
+
+PyPI distribution name is **`guap-lab-auto`**; entry point remains **`lab-auto`**. See README § Publishing.

guap_lab_auto-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lab-automation contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guap_lab_auto-0.1.0/MANIFEST.in

@@ -0,0 +1,9 @@
+include README.md
+include LICENSE
+include AGENTS.md
+include MANIFEST.in
+graft skills
+graft .agents
+graft docs
+graft examples
+graft scripts