progi 0.1.0__tar.gz

progi-0.1.0/.env.example

@@ -0,0 +1,15 @@
+# Copy this file to .env and adjust values for your local setup.
+# All variables are optional — defaults are shown in comments.
+
+# Path to the SQLite database file.
+# Default: OS user data dir (e.g. ~/.local/share/progi/progi.db on Linux)
+# PROGI_DB_PATH=/path/to/progi.db
+
+# Web server host. Default: 127.0.0.1 (localhost only — do not expose on a network interface)
+# PROGI_WEB_HOST=127.0.0.1
+
+# Web server port. Default: 8000
+# PROGI_WEB_PORT=8000
+
+# Set to 1 to disable the web server entirely.
+# PROGI_NO_WEB=0

progi-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-caching: true
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Lint
+        run: uv run ruff check progi
+
+      - name: Test
+        run: uv run python -m pytest

progi-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,47 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-caching: true
+
+      - name: Build
+        run: uv build
+
+      - name: Check dist metadata
+        run: uvx twine check dist/*
+
+      - name: Upload dist artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download dist artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

progi-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Python
+__pycache__/
+*.pyc
+.venv/
+*.egg-info/
+dist/
+build/
+
+# Frontend build artifacts (downloaded/generated, not committed)
+# style.css IS committed — it ships in the wheel so uvx installs work without a build step
+frontend/tailwindcss
+frontend/tailwindcss.exe
+
+# Vendored JS IS committed (no CDN at runtime) — do not ignore vendor/
+
+# Local databases
+*.db
+*.db-wal
+*.db-shm
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+
+
+.env
+.vscode/
+.agents/
+.claude/
+.mcp.json
+
+# Alembic generated migrations (local only)
+alembic/versions/

progi-0.1.0/AGENTS.md

@@ -0,0 +1,173 @@
+# AGENTS.md
+
+## What this is
+
+Progi is an MCP-native workflow engine. Key terms:
+
+- **workflow**: a reusable template of ordered **steps**; defines a repeatable, reused across many tasks
+- **step**: one unit of work in a workflow; has a **playbook**, an input spec, and an output spec
+- **playbook**: markdown attached to a step; the agent reads it via `start_or_continue_task` and follows it
+- **task**: a single execution of a workflow; progresses through steps one at a time with lifecycle `todo` → `in_progress` → `done`
+
+Two interfaces over one SQLite DB:
+
+- **Progi MCP server** (FastMCP, stdio) — the work loop runs here, inside the user's harness.
+- **Progi Monitoring** (FastAPI + Jinja + Alpine/AlpineAJAX) — a web app for tracking tasks and reviewing workflows.
+
+## The one rule
+
+**All database access goes through `progi/db.py`.** MCP tools and web routes
+are thin adapters that call named functions there — they never write SQL. This is
+what keeps LLM-driven and human-driven edits behaviorally identical.
+
+## Layout
+
+| File | Role |
+|---|---|
+| `progi/db.py` | Schema (SQLAlchemy Core) + **all** queries, mutations, and state-transition logic |
+| `progi/mcp_server.py` | `@mcp.tool` wrappers (work loop + workflow authoring) |
+| `progi/web/app.py` | FastAPI routes → Jinja partials |
+| `progi/prompts/` | Pass 1 / Pass 2 authoring system prompts (served by tools) |
+| `progi/seed.py` | "Blog Post" workflow + sample task (idempotent) |
+| `tests/test_db.py` | DB roundtrip, full work loop, authoring |
+
+## Frontend / UI components
+
+Templates live in `progi/web/templates/`. The UI stack is:
+
+- **Tailwind CSS v4** (compiled by the standalone CLI via `just build`)
+- **Alpine.js v3** + **Alpine AJAX** — vendored to `static/vendor/` by `just vendorize`
+- **PenguinUI** — a copy-paste component library; no install needed
+
+### Using PenguinUI
+
+Browse components at **https://www.penguinui.com/components**, pick what you need,
+and paste the HTML directly into a template. There is nothing to download or import —
+PenguinUI components are just Tailwind + Alpine markup.
+
+Key conventions when adding components:
+- Use `<article>` as the root for card-style components (PenguinUI's convention).
+- Use the existing design tokens from `frontend/input.css` (`bg-surface-*`,
+  `text-primary`, `text-accent`, `border-subtle`, etc.) instead of raw colors.
+- Interactive components that require Alpine plugins (Collapse, Focus, Mask) must
+  vendorize those scripts via `just vendorize` and load them **before** Alpine core
+  in `base.html` (plugins must register before Alpine initializes).
+- Web routes return **HTML partials** for AJAX; the swapped element's `id` must
+  match the `x-target` attribute on the trigger element.
+
+### Adding a new top-level page
+
+Pages live in `progi/web/templates/pages/`. Each page template extends a
+variable base template so the same file works for both full page loads and
+Alpine AJAX partial swaps — no separate `*_content.html` partial needed.
+
+**1. Template** (`pages/mypage.html`):
+
+```html
+{% extends base_template %}
+
+{% block content %}
+<!-- page content here -->
+{% endblock %}
+```
+
+If the page needs full-bleed layout (no max-width wrapper), also override
+`outer_class` as an empty block (see `pages/workflows.html`).
+
+**2. Router** (`routers/mypage.py`):
+
+```python
+from . import base_template
+
+@router.get("/mypage", response_class=HTMLResponse)
+def mypage(request: Request):
+    ctx = {"base_template": base_template(request), ...}
+    return _templates(request).TemplateResponse(request, "pages/mypage.html", ctx)
+```
+
+Always pass `"base_template": base_template(request)` in the context.
+`base_template()` returns `"base_partial.html"` for Alpine AJAX requests and
+`"base.html"` for direct browser navigation. `base_partial.html` wraps the
+content in `<div id="page-content">` so Alpine AJAX can find its swap target.
+
+**3. Nav link** (`base.html`):
+
+```html
+<a href="/mypage"
+   x-target.push="page-content"
+   :class="{ 'text-primary': page === '/mypage', 'text-faint hover:text-muted': page !== '/mypage' }"
+   class="text-xs font-medium transition-colors duration-150"
+   x-cloak>
+  My Page
+</a>
+```
+
+**4. Register the router** (`web/app.py`):
+
+```python
+from .routers import board, mypage, workflows
+app.include_router(mypage.router)
+```
+
+## Conventions
+
+- **No SQL outside `db.py`.** Add a named function; wrap writes in `with engine.begin()`.
+- **Never `print()` / write to stdout** anywhere reachable from the MCP process — stdout is the MCP protocol channel. Log to stderr via `logging_setup`.
+- **Web returns HTML partials** for AJAX (not JSON); the swapped element's `id` must match the trigger's `x-target`.
+- `input_spec` / `output_spec` / `input_data` / `output` are `sa.JSON` columns — pass and receive plain dicts, no manual `json.dumps`.
+- Keep the web UI localhost-only (unauthenticated DB viewer).
+
+### Choosing between fetch + JS state vs. Alpine AJAX partials
+
+Use **plain `fetch` + Alpine reactive state** (in `app.js`) when:
+- The backend returns no meaningful body (e.g. 204 on DELETE)
+- The UI update is a local state mutation — remove an item, clear a field, reset a flag
+- No new HTML needs to come from the server
+
+Use **Alpine AJAX / HTML partials** when:
+- The server is the source of truth for what to render (e.g. a detail panel, a refreshed list)
+- The response *is* the UI update — swapping in rendered HTML is simpler than rebuilding it in JS
+
+#### Alpine AJAX trigger pattern
+
+Alpine AJAX intercepts clicks on `<a href>` elements and form submits — **not** bare button clicks. For any clickable element that should trigger an AJAX swap, wrap it in an `<a>` tag with `href` pointing to the endpoint and `x-target` naming the element ID to replace:
+
+```html
+<a href="/board" x-target="board" class="...">
+  Refresh
+</a>
+```
+
+If you also need to send a payload to backend, use `<FORM>` instead of `<a>`.
+
+Omit `.push` on `x-target` when you don't want the click to update the browser history (e.g. a refresh action vs. navigation).
+
+Example of the fetch pattern (workflow delete in `app.js`):
+```js
+const resp = await fetch(`/workflows/${id}`, { method: 'DELETE' });
+if (resp.ok) {
+  this.workflows = this.workflows.filter(wf => wf.id !== id);
+  // clear canvas, reset active state, update URL as needed
+}
+```
+
+## Dev commands
+
+`just` ships in the dev group, so prefix recipes with `uv run` if you don't have a system `just`.
+
+```bash
+uv sync --extra dev                  # deps + just
+uv run just install                  # + vendored JS, Tailwind CLI
+uv run just build                    # compile web/static/style.css
+uv run just dev                      # web app with autoreload
+uv run just mcp                      # MCP server only (stdio)
+uv run just migrate "msg" && uv run just upgrade   # Alembic migration
+uv run just seed                     # load Blog Post workflow + sample task
+uv run python -m pytest              # tests (do NOT use `uv run pytest` — a system pytest may shadow it)
+uv run ruff check progi              # lint
+```
+
+## Run modes
+
+`progi` (MCP + web), `progi --no-web` (MCP only), `progi-web` (web only).
+Config via env: `PROGI_DB_PATH`, `PROGI_WEB_HOST`, `PROGI_WEB_PORT`, `PROGI_NO_WEB`.

progi-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-06-15
+
+### Added
+
+- Initial release.
+
+[0.1.0]: https://github.com/ateszika/progi/releases/tag/v0.1.0

progi-0.1.0/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

progi-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,19 @@
+# Contributing to Progi
+
+## Before submitting a PR
+Run this:
+```bash
+uv run ruff check src
+uv run python -m pytest
+```
+
+Both must pass.
+
+Do not submit code that was not reviewed by you (the human). Make sure that you have a good understanding of the code changes you want to introduce.
+
+If you are using agents to code, we have an `AGENTS.md` you should use.
+
+Do not edit `CHANGELOG.md`. Changelog entries are added by maintainers.
+
+## Docs & content PRs
+You can submit documentation fixes or even new guides/tutorials to share how you use Progi - use cases, workflow examples etc...

progi-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Progi 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.

progi-0.1.0/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.4
+Name: progi
+Version: 0.1.0
+Summary: An MCP-native workflow engine that teaches your agent how you like to get things done.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: alembic>=1.13
+Requires-Dist: fastapi>=0.115
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: platformdirs>=4.0
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: uvicorn>=0.30
+Provides-Extra: dev
+Requires-Dist: httpx>=0.27; extra == 'dev'
+Requires-Dist: mcp[cli]>=1.27.2; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Progi - MCP-native Workflow Engine
+
+Progi teaches your agent how **you** like to get things done. So you can do your best work without re-explaining your process or losing context between sessions.
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/progi)](https://pypi.org/project/progi/)
+[![PyPI](https://img.shields.io/pypi/v/progi)](https://pypi.org/project/progi/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-6366f1)](https://modelcontextprotocol.io)
+
+---
+
+## Get started
+
+Add Progi to your MCP client config (VS Code / Cursor / Zed / Claude Code / etc):
+
+```json
+{
+  "mcpServers": {
+    "progi": {
+      "command": "uvx",
+      "args": ["progi"]
+    }
+  }
+}
+```
+
+Or with the Claude Code CLI:
+
+```bash
+claude mcp add progi -- uvx progi
+```
+
+Requires [uv](https://docs.astral.sh/uv/). That's it — your AI now has tools to create workflows, follow playbooks step by step, and keep a kanban board current. The web UI (Progi Monitoring) starts automatically at `http://127.0.0.1:8000`.
+
+---
+
+## How it works
+
+**1. Describe your workflow**
+
+Describe your process in plain language. You can be detailed or just provide a rough idea. Progi stores it as a structured workflow with per-step playbooks.
+
+**2. Run tasks, stay in the loop**
+
+*"Hey Progi, continue working on xy task."* Your agent loads the workflow, works through each step using your playbooks, and loops you in at critical checkpoints to review output.
+
+**3. Monitor progress**
+
+Progi Monitoring gives you a live view of every running and completed task — status, progress, and the full output history across all your workflows.
+
+**4. Optimize as you go**
+
+Tweak playbooks between runs. Because workflows live in a database and survive context resets, every future task picks up your changes automatically — your process gets sharper with each iteration.
+
+---
+
+## MCP Tools
+
+### Work loop
+
+| Tool | Description |
+|---|---|
+| `create_task` | Create a new task under a given workflow (status `todo`); returns a preview of its first step |
+| `list_tasks` | List tasks, optionally filtered by status and/or workflow |
+| `start_or_continue_task` | Main work-loop entry point — starts or resumes a task and returns the current step's playbook, input data, and output spec |
+| `update_progress_notes` | Overwrite a task's progress notes (mid-step save point) |
+| `submit_output` | Mark the current step complete, store its output, and advance to the next step (or mark done) |
+
+### Workflow authoring
+
+| Tool | Description |
+|---|---|
+| `get_process_skeleton_prompt` | Return the Pass 1 system prompt for turning a plain-language description into a structured workflow skeleton |
+| `get_playbook_authoring_prompt` | Return the Pass 2 system prompt for authoring a step's playbook (injects workflow context) |
+| `save_workflow` | Persist a new workflow, its steps, and playbooks |
+| `list_workflows` | Return all workflows with their ordered steps |
+| `update_playbook` | Replace the playbook content for a step |
+
+Authoring is two passes: Pass 1 turns a plain-language description into a structured skeleton; Pass 2 authors each step's playbook. `save_workflow` persists both.
+
+---
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PROGI_DB_PATH` | OS data dir (`platformdirs`) | SQLite file location |
+| `PROGI_WEB_HOST` | `127.0.0.1` | Web UI bind host |
+| `PROGI_WEB_PORT` | `8000` | Web UI port |
+| `PROGI_NO_WEB` | `0` | Set to `1` to disable the web UI |
+
+Run modes: `uvx progi` (MCP + web UI), `uvx progi --no-web` (MCP only), `uvx progi-web` (web UI only).
+
+> Use an absolute path for `PROGI_DB_PATH`
+
+---
+
+## License
+
+MIT

progi-0.1.0/README.md

@@ -0,0 +1,101 @@
+# Progi - MCP-native Workflow Engine
+
+Progi teaches your agent how **you** like to get things done. So you can do your best work without re-explaining your process or losing context between sessions.
+
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/progi)](https://pypi.org/project/progi/)
+[![PyPI](https://img.shields.io/pypi/v/progi)](https://pypi.org/project/progi/)
+[![MCP](https://img.shields.io/badge/MCP-compatible-6366f1)](https://modelcontextprotocol.io)
+
+---
+
+## Get started
+
+Add Progi to your MCP client config (VS Code / Cursor / Zed / Claude Code / etc):
+
+```json
+{
+  "mcpServers": {
+    "progi": {
+      "command": "uvx",
+      "args": ["progi"]
+    }
+  }
+}
+```
+
+Or with the Claude Code CLI:
+
+```bash
+claude mcp add progi -- uvx progi
+```
+
+Requires [uv](https://docs.astral.sh/uv/). That's it — your AI now has tools to create workflows, follow playbooks step by step, and keep a kanban board current. The web UI (Progi Monitoring) starts automatically at `http://127.0.0.1:8000`.
+
+---
+
+## How it works
+
+**1. Describe your workflow**
+
+Describe your process in plain language. You can be detailed or just provide a rough idea. Progi stores it as a structured workflow with per-step playbooks.
+
+**2. Run tasks, stay in the loop**
+
+*"Hey Progi, continue working on xy task."* Your agent loads the workflow, works through each step using your playbooks, and loops you in at critical checkpoints to review output.
+
+**3. Monitor progress**
+
+Progi Monitoring gives you a live view of every running and completed task — status, progress, and the full output history across all your workflows.
+
+**4. Optimize as you go**
+
+Tweak playbooks between runs. Because workflows live in a database and survive context resets, every future task picks up your changes automatically — your process gets sharper with each iteration.
+
+---
+
+## MCP Tools
+
+### Work loop
+
+| Tool | Description |
+|---|---|
+| `create_task` | Create a new task under a given workflow (status `todo`); returns a preview of its first step |
+| `list_tasks` | List tasks, optionally filtered by status and/or workflow |
+| `start_or_continue_task` | Main work-loop entry point — starts or resumes a task and returns the current step's playbook, input data, and output spec |
+| `update_progress_notes` | Overwrite a task's progress notes (mid-step save point) |
+| `submit_output` | Mark the current step complete, store its output, and advance to the next step (or mark done) |
+
+### Workflow authoring
+
+| Tool | Description |
+|---|---|
+| `get_process_skeleton_prompt` | Return the Pass 1 system prompt for turning a plain-language description into a structured workflow skeleton |
+| `get_playbook_authoring_prompt` | Return the Pass 2 system prompt for authoring a step's playbook (injects workflow context) |
+| `save_workflow` | Persist a new workflow, its steps, and playbooks |
+| `list_workflows` | Return all workflows with their ordered steps |
+| `update_playbook` | Replace the playbook content for a step |
+
+Authoring is two passes: Pass 1 turns a plain-language description into a structured skeleton; Pass 2 authors each step's playbook. `save_workflow` persists both.
+
+---
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `PROGI_DB_PATH` | OS data dir (`platformdirs`) | SQLite file location |
+| `PROGI_WEB_HOST` | `127.0.0.1` | Web UI bind host |
+| `PROGI_WEB_PORT` | `8000` | Web UI port |
+| `PROGI_NO_WEB` | `0` | Set to `1` to disable the web UI |
+
+Run modes: `uvx progi` (MCP + web UI), `uvx progi --no-web` (MCP only), `uvx progi-web` (web UI only).
+
+> Use an absolute path for `PROGI_DB_PATH`
+
+---
+
+## License
+
+MIT

progi-0.1.0/alembic/env.py

@@ -0,0 +1,58 @@
+"""Alembic environment, wired to progi's config and Core metadata."""
+
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from progi.config import load_config
+from progi.models import metadata
+
+config = context.config
+
+# Resolve the DB URL from progi's own config so migrations and the app always
+# point at the same database.
+_cfg = load_config()
+_cfg.ensure_dirs()
+config.set_main_option("sqlalchemy.url", _cfg.sqlalchemy_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        render_as_batch=True,  # required for SQLite ALTER support
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            render_as_batch=True,  # SQLite-safe migrations
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

progi-0.1.0/alembic/script.py.mako

@@ -0,0 +1,24 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}