Metadata-Version: 2.4
Name: gtm-admin
Version: 0.5.24
Summary: Workflow monitoring and management for FastAPI apps
License: MIT License
        
        Copyright (c) 2026 GTM Admin 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.
License-File: LICENSE
Classifier: Framework :: FastAPI
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: alembic>=1.14.0
Requires-Dist: apscheduler>=3.10.0
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: bcrypt>=4.0.0
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: sqlmodel>=0.0.22
Requires-Dist: uvicorn[standard]>=0.32.0
Provides-Extra: dev
Requires-Dist: build>=1.0.0; extra == 'dev'
Requires-Dist: hatchling>=1.25.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: twine>=5.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# gtm-admin

Workflow monitoring and management for FastAPI apps.

`gtm-admin` adds a self-hosted dashboard and run-tracking API to **any FastAPI application**. Decorate Python functions with `@gtm.workflow` and choose how they are triggered: manually, on a cron schedule, or via a webhook.

**[Full documentation → DOCS.md](../DOCS.md)**

## Install

```bash
pip install gtm-admin

# Required for cron-scheduled workflows:
pip install apscheduler
```

## Quick start

```python
import os
from fastapi import FastAPI
from gtm_admin import GTMAdmin

app = FastAPI()

gtm = GTMAdmin(
    app,
    db_url=os.environ["GTM_DB_URL"],
    secret=os.environ["GTM_SECRET"],
)

@gtm.workflow
async def enrich_leads(inputs: dict):
    results = call_some_api(inputs["leads"])
    return {"enriched": results}

@gtm.workflow(cron="0 9 * * 1-5")
async def daily_sync(inputs: dict):
    return {"synced": sync_database()}

@gtm.workflow(webhook=True)
async def process_event(inputs: dict):
    return handle(inputs)
```

This mounts the dashboard at `/admin/` and the REST API at `/api/*` on your FastAPI app. See [DOCS.md](../DOCS.md) for the full reference — constructor options, workflow decorator options, nodes, config store, data tables (including row filtering with `RowFilter`), and deployment.

## API Routes

All routes are mounted under `/api` on your FastAPI app.

| Method    | Path                                | Auth | Description                                |
| --------- | ----------------------------------- | ---- | ------------------------------------------ |
| POST      | `/api/auth/token`                   | —    | Log in; returns a JWT access token         |
| POST      | `/api/auth/register`                | —    | Register a new user account                |
| GET       | `/api/health`                       | —    | Health check                               |
| POST      | `/api/webhooks/{name}`              | —    | Invoke a webhook-enabled workflow          |
| GET       | `/api/workflow-runs`                | ✓    | Paginated list of runs (filterable)        |
| GET       | `/api/workflow-runs/stats`          | ✓    | Status counts + active/recent run lists    |
| GET       | `/api/workflow-runs/{id}`           | ✓    | Full run detail with nodes                 |
| POST      | `/api/workflow-runs/{id}/rerun`     | ✓    | Re-execute a workflow with the same inputs |
| POST      | `/api/workflow-runs/{id}/cancel`    | ✓    | Cancel a specific pending or running run   |
| POST      | `/api/workflow-runs/cancel-pending` | ✓    | Cancel all pending (queued) runs           |
| POST      | `/api/workflow-runs/cancel-all`     | ✓    | Cancel all pending and running runs        |
| GET       | `/api/config`                       | ✓    | List all config records                    |
| POST      | `/api/config`                       | ✓    | Create a config record                     |
| PATCH     | `/api/config/{id}`                  | ✓    | Update a config record                     |
| DELETE    | `/api/config/{id}`                  | ✓    | Delete a config record                     |
| GET       | `/api/db-tables`                    | ✓    | List all data tables                       |
| POST      | `/api/db-tables`                    | ✓    | Create a table                             |
| PATCH     | `/api/db-tables/{id}`               | ✓    | Update a table's schema or rows            |
| DELETE    | `/api/db-tables/{id}`               | ✓    | Delete a table                             |
| WebSocket | `/api/ws?token=<jwt>`               | ✓    | Real-time event stream                     |
| GET       | `/admin/`                           | —    | Dashboard SPA                              |

## Package structure

```
api/
├── src/gtm_admin/          # The published library
│   ├── __init__.py         # Exports GTMAdmin
│   ├── core.py             # GTMAdmin class — mounts router + dashboard
│   ├── auth.py             # JWT creation/verification + bcrypt helpers
│   ├── database.py         # Async SQLAlchemy engine + session factory + migrations
│   ├── decorator.py        # @gtm.workflow — wraps functions with run capture logic
│   ├── deps.py             # get_current_user FastAPI dependency
│   ├── models.py           # WorkflowRun, User, ConfigRecord, DbTable SQLModel models
│   ├── router.py           # All API route handlers + Pydantic response schemas
│   ├── seed.py             # Demo data seeder (used by auto_seed=True)
│   └── static/             # Built React SPA (populated by `pnpm run build`)
├── app/                    # Standalone FastAPI app for local development
│   ├── main.py             # App entry point — includes all routers + Vite proxy
│   ├── auth.py             # Auth helpers
│   ├── config.py           # pydantic-settings config (DATABASE_URL, SECRET_KEY)
│   ├── database.py         # Engine + session setup for the standalone app
│   ├── deps.py             # FastAPI dependencies
│   ├── models/             # SQLModel models (WorkflowRun, User, ConfigRecord, DbTable)
│   └── routers/            # auth, workflow_runs, configs, db_tables, execution_buckets
├── alembic/                # Database migrations for the standalone dev app
├── seed.py                 # Seed script (run directly: uv run python seed.py)
├── hatch_build.py          # Build hook — runs `pnpm run build` before packaging
└── pyproject.toml          # Package metadata + hatchling build config
```

## Local development

```bash
cd api
cp .env.example .env        # Set DATABASE_URL and SECRET_KEY
uv sync
uv run alembic upgrade head
uv run python seed.py       # Optional: seed demo data
```

Run the standalone dev server from the monorepo root:

```bash
make dev-api      # FastAPI on :8080 with GTM_DEV=true
make dev-frontend # Vite on :5173 (run concurrently for HMR)
make dev          # Both at once
```

## Requirements

- Python 3.11+
- PostgreSQL database (Supabase, Neon, or self-hosted)
- FastAPI app

## License

MIT
