gtm-admin 0.1.0__tar.gz

gtm_admin-0.1.0/.env.example

@@ -0,0 +1,3 @@
+DATABASE_URL=postgresql://user:password@localhost:5432/gtm_admin
+SECRET_KEY=change-me-to-a-random-secret-key
+ACCESS_TOKEN_EXPIRE_MINUTES=30

gtm_admin-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Python / uv
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+.uv/
+.uv-cache/
+*.so
+.env
+.env.*
+!.env.example
+
+# Generated static files — produced at build time, never committed
+api/src/gtm_admin/static/
+
+# Node / Vite
+node_modules/
+dist/
+dist-ssr/
+*.local
+.pnpm-store/
+
+# Logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Editor / OS
+.DS_Store
+.vscode/
+.idea/
+*.swp
+*.swo
+Thumbs.db

gtm_admin-0.1.0/LICENSE

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

gtm_admin-0.1.0/Makefile

@@ -0,0 +1,10 @@
+.PHONY: init dev
+
+init:
+	cp -n .env.example .env || true
+	uv sync
+	alembic revision --autogenerate -m "initial"
+	alembic upgrade head
+
+dev:
+	uv run uvicorn app.main:app --reload

gtm_admin-0.1.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: gtm-admin
+Version: 0.1.0
+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: asyncpg>=0.30.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+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** with zero infrastructure setup. You write pure Python workflow functions — it handles capture, persistence, and visualization.
+
+## Install
+
+```bash
+pip install gtm-admin
+```
+
+## Usage
+
+```python
+import os
+from fastapi import FastAPI
+from gtm_admin import GTMAdmin
+
+app = FastAPI()
+
+gtm = GTMAdmin(
+    app,
+    db_url=os.environ["GTM_DB_URL"],    # postgresql://... connection string
+    secret=os.environ["GTM_SECRET"],    # random secret for JWT signing
+)
+
+@gtm.workflow
+async def enrich_leads(inputs: dict):
+    """Each decorated function becomes a tracked workflow."""
+    results = call_some_api(inputs["leads"])
+    return {"enriched": results}
+```
+
+This mounts:
+- **`/admin`** — React dashboard SPA (run history, status, I/O inspection)
+- **`/api/*`** — REST API consumed by the dashboard
+
+## Routes
+
+| Path | Description |
+|------|-------------|
+| `/api/runs` | List all workflow runs |
+| `/api/runs/{id}` | Run detail (inputs, outputs, timing, errors) |
+| `/api/workflows` | List registered workflows |
+| `/api/health` | Health check |
+| `/admin/` | Dashboard SPA |
+
+## Deployment (Digital Ocean App Platform)
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install gtm-admin
+RUN pip install -r requirements.txt
+COPY . .
+EXPOSE 8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+Set in DO console: `GTM_DB_URL` (Supabase/Neon), `GTM_SECRET`.
+
+## Development mode
+
+In dev mode, `/admin/*` is proxied to a Vite HMR server instead of serving static files:
+
+```python
+gtm = GTMAdmin(app, db_url=..., secret=..., dev=os.getenv("GTM_DEV") == "true")
+```
+
+## Requirements
+
+- Python 3.11+
+- PostgreSQL database (Supabase, Neon, or self-hosted)
+- FastAPI app
+
+## License
+
+MIT

gtm_admin-0.1.0/README.md

@@ -0,0 +1,80 @@
+# gtm-admin
+
+Workflow monitoring and management for FastAPI apps.
+
+`gtm-admin` adds a self-hosted dashboard and run-tracking API to **any FastAPI application** with zero infrastructure setup. You write pure Python workflow functions — it handles capture, persistence, and visualization.
+
+## Install
+
+```bash
+pip install gtm-admin
+```
+
+## Usage
+
+```python
+import os
+from fastapi import FastAPI
+from gtm_admin import GTMAdmin
+
+app = FastAPI()
+
+gtm = GTMAdmin(
+    app,
+    db_url=os.environ["GTM_DB_URL"],    # postgresql://... connection string
+    secret=os.environ["GTM_SECRET"],    # random secret for JWT signing
+)
+
+@gtm.workflow
+async def enrich_leads(inputs: dict):
+    """Each decorated function becomes a tracked workflow."""
+    results = call_some_api(inputs["leads"])
+    return {"enriched": results}
+```
+
+This mounts:
+- **`/admin`** — React dashboard SPA (run history, status, I/O inspection)
+- **`/api/*`** — REST API consumed by the dashboard
+
+## Routes
+
+| Path | Description |
+|------|-------------|
+| `/api/runs` | List all workflow runs |
+| `/api/runs/{id}` | Run detail (inputs, outputs, timing, errors) |
+| `/api/workflows` | List registered workflows |
+| `/api/health` | Health check |
+| `/admin/` | Dashboard SPA |
+
+## Deployment (Digital Ocean App Platform)
+
+```dockerfile
+FROM python:3.11-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install gtm-admin
+RUN pip install -r requirements.txt
+COPY . .
+EXPOSE 8080
+CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
+```
+
+Set in DO console: `GTM_DB_URL` (Supabase/Neon), `GTM_SECRET`.
+
+## Development mode
+
+In dev mode, `/admin/*` is proxied to a Vite HMR server instead of serving static files:
+
+```python
+gtm = GTMAdmin(app, db_url=..., secret=..., dev=os.getenv("GTM_DEV") == "true")
+```
+
+## Requirements
+
+- Python 3.11+
+- PostgreSQL database (Supabase, Neon, or self-hosted)
+- FastAPI app
+
+## License
+
+MIT

gtm_admin-0.1.0/alembic/env.py

@@ -0,0 +1,45 @@
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+from sqlmodel import SQLModel
+
+from app.config import settings
+import app.models  # noqa: F401 — ensure all models are registered
+
+config = context.config
+config.set_main_option("sqlalchemy.url", settings.database_url)
+
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+target_metadata = SQLModel.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=settings.database_url,
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+    )
+    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)
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

gtm_admin-0.1.0/alembic/script.py.mako

@@ -0,0 +1,26 @@
+"""${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
+import sqlmodel
+${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"}

gtm_admin-0.1.0/alembic.ini

@@ -0,0 +1,38 @@
+[alembic]
+script_location = src/gtm_admin/migrations
+prepend_sys_path = src
+version_path_separator = os
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

gtm_admin-0.1.0/app/auth.py

@@ -0,0 +1,21 @@
+from datetime import datetime, timedelta, timezone
+
+from jose import jwt
+from passlib.context import CryptContext
+
+from app.config import settings
+
+pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
+
+
+def hash_password(password: str) -> str:
+    return pwd_context.hash(password)
+
+
+def verify_password(plain: str, hashed: str) -> bool:
+    return pwd_context.verify(plain, hashed)
+
+
+def create_access_token(subject: str) -> str:
+    expire = datetime.now(timezone.utc) + timedelta(minutes=settings.access_token_expire_minutes)
+    return jwt.encode({"sub": subject, "exp": expire}, settings.secret_key, algorithm="HS256")

gtm_admin-0.1.0/app/config.py

@@ -0,0 +1,16 @@
+from pydantic_settings import BaseSettings
+
+
+class Settings(BaseSettings):
+    database_url: str
+    secret_key: str
+    access_token_expire_minutes: int = 30
+
+    @property
+    def async_database_url(self) -> str:
+        return self.database_url.replace("postgresql://", "postgresql+asyncpg://", 1)
+
+    model_config = {"env_file": ".env"}
+
+
+settings = Settings()

gtm_admin-0.1.0/app/database.py

@@ -0,0 +1,16 @@
+from collections.abc import AsyncGenerator
+
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import sessionmaker
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.config import settings
+
+engine = create_async_engine(settings.async_database_url)
+
+AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
+
+
+async def get_session() -> AsyncGenerator[AsyncSession, None]:
+    async with AsyncSessionLocal() as session:
+        yield session

gtm_admin-0.1.0/app/deps.py

@@ -0,0 +1,33 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError, jwt
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.config import settings
+from app.database import get_session
+from app.models.user import User
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/auth/token")
+
+
+async def get_current_user(
+    token: str = Depends(oauth2_scheme),
+    session: AsyncSession = Depends(get_session),
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid credentials",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = jwt.decode(token, settings.secret_key, algorithms=["HS256"])
+        username: str | None = payload.get("sub")
+        if username is None:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    user = await session.get(User, username)
+    if user is None:
+        raise credentials_exception
+    return user

gtm_admin-0.1.0/app/main.py

@@ -0,0 +1,8 @@
+from fastapi import FastAPI
+
+from app.routers import auth, workflow_runs
+
+app = FastAPI(title="GTM Admin API")
+
+app.include_router(auth.router)
+app.include_router(workflow_runs.router)

gtm_admin-0.1.0/app/models/__init__.py

@@ -0,0 +1,4 @@
+from app.models.user import User
+from app.models.workflow_run import WorkflowRun
+
+__all__ = ["User", "WorkflowRun"]

gtm_admin-0.1.0/app/models/user.py

@@ -0,0 +1,22 @@
+from datetime import datetime, timezone
+
+from sqlmodel import Field, SQLModel
+
+
+class UserBase(SQLModel):
+    username: str = Field(primary_key=True)
+
+
+class User(UserBase, table=True):
+    __tablename__ = "users"
+
+    hashed_password: str
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class UserCreate(UserBase):
+    password: str
+
+
+class UserRead(UserBase):
+    created_at: datetime

gtm_admin-0.1.0/app/models/workflow_run.py

@@ -0,0 +1,42 @@
+from datetime import datetime, timezone
+from enum import Enum
+from uuid import UUID, uuid4
+
+from sqlmodel import Field, SQLModel
+
+
+class WorkflowStatus(str, Enum):
+    pending = "pending"
+    running = "running"
+    success = "success"
+    failed = "failed"
+
+
+class WorkflowRunBase(SQLModel):
+    name: str
+    status: WorkflowStatus = WorkflowStatus.pending
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class WorkflowRun(WorkflowRunBase, table=True):
+    __tablename__ = "workflow_runs"
+
+    id: UUID = Field(default_factory=uuid4, primary_key=True)
+    created_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+
+
+class WorkflowRunCreate(WorkflowRunBase):
+    pass
+
+
+class WorkflowRunUpdate(SQLModel):
+    name: str | None = None
+    status: WorkflowStatus | None = None
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+
+class WorkflowRunRead(WorkflowRunBase):
+    id: UUID
+    created_at: datetime

gtm_admin-0.1.0/app/routers/auth.py

@@ -0,0 +1,31 @@
+from fastapi import APIRouter, Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordRequestForm
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.auth import create_access_token, hash_password, verify_password
+from app.database import get_session
+from app.models.user import User, UserCreate, UserRead
+
+router = APIRouter(prefix="/auth", tags=["auth"])
+
+
+@router.post("/token")
+async def login(
+    form: OAuth2PasswordRequestForm = Depends(),
+    session: AsyncSession = Depends(get_session),
+):
+    user = await session.get(User, form.username)
+    if not user or not verify_password(form.password, user.hashed_password):
+        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid credentials")
+    return {"access_token": create_access_token(user.username), "token_type": "bearer"}
+
+
+@router.post("/register", response_model=UserRead, status_code=status.HTTP_201_CREATED)
+async def register(body: UserCreate, session: AsyncSession = Depends(get_session)):
+    if await session.get(User, body.username):
+        raise HTTPException(status_code=status.HTTP_409_CONFLICT, detail="Username already exists")
+    user = User(username=body.username, hashed_password=hash_password(body.password))
+    session.add(user)
+    await session.commit()
+    await session.refresh(user)
+    return user

gtm_admin-0.1.0/app/routers/workflow_runs.py

@@ -0,0 +1,77 @@
+from uuid import UUID
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlmodel import select
+from sqlmodel.ext.asyncio.session import AsyncSession
+
+from app.database import get_session
+from app.deps import get_current_user
+from app.models.user import User
+from app.models.workflow_run import WorkflowRun, WorkflowRunCreate, WorkflowRunRead, WorkflowRunUpdate
+
+router = APIRouter(prefix="/workflow-runs", tags=["workflow-runs"])
+
+
+@router.get("", response_model=list[WorkflowRunRead])
+async def list_workflow_runs(
+    session: AsyncSession = Depends(get_session),
+    _: User = Depends(get_current_user),
+):
+    result = await session.exec(select(WorkflowRun))
+    return result.all()
+
+
+@router.get("/{id}", response_model=WorkflowRunRead)
+async def get_workflow_run(
+    id: UUID,
+    session: AsyncSession = Depends(get_session),
+    _: User = Depends(get_current_user),
+):
+    run = await session.get(WorkflowRun, id)
+    if not run:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow run not found")
+    return run
+
+
+@router.post("", response_model=WorkflowRunRead, status_code=status.HTTP_201_CREATED)
+async def create_workflow_run(
+    body: WorkflowRunCreate,
+    session: AsyncSession = Depends(get_session),
+    _: User = Depends(get_current_user),
+):
+    run = WorkflowRun.model_validate(body)
+    session.add(run)
+    await session.commit()
+    await session.refresh(run)
+    return run
+
+
+@router.patch("/{id}", response_model=WorkflowRunRead)
+async def update_workflow_run(
+    id: UUID,
+    body: WorkflowRunUpdate,
+    session: AsyncSession = Depends(get_session),
+    _: User = Depends(get_current_user),
+):
+    run = await session.get(WorkflowRun, id)
+    if not run:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow run not found")
+    for field, value in body.model_dump(exclude_unset=True).items():
+        setattr(run, field, value)
+    session.add(run)
+    await session.commit()
+    await session.refresh(run)
+    return run
+
+
+@router.delete("/{id}", status_code=status.HTTP_204_NO_CONTENT)
+async def delete_workflow_run(
+    id: UUID,
+    session: AsyncSession = Depends(get_session),
+    _: User = Depends(get_current_user),
+):
+    run = await session.get(WorkflowRun, id)
+    if not run:
+        raise HTTPException(status_code=status.HTTP_404_NOT_FOUND, detail="Workflow run not found")
+    await session.delete(run)
+    await session.commit()