ai-agents-marketplace solves that with a single principle: author once, render many. It ships an interactive CLI (agents-marketplace) that distributes three kinds of reusable agent context — skills 🧠, plugins 🔌, and rules 📏 — into any project, rendering each artifact into the native format every supported agent actually reads.

The core idea

There are two distribution problems, and the tool treats them differently:

• Skills and plugins are universal. You author them once and install them into shared open-standard directories (.claude/skills/, .agents/skills/) that many agents already read natively. No per-agent rendering needed.
• Rules are agent-specific. Each agent has its own rules format, frontmatter, and location. So one authored rule is rendered into up to five native formats at install time — Cursor MDC, Copilot instructions, and Markdown-plus-frontmatter for Claude, Codex, and Gemini.

That split is the whole design. The universal artifacts ride on conventions that already exist; the fragmented ones get a render pipeline so you never write the same rule five times.

Quick start

1. Fork the repo

Start by forking ai-agents-marketplace on GitHub. This gives you your own catalog — you can add your own skills and rules, customize existing ones, and still pull upstream when new artifacts are added. Running directly from the original repo works for a quick try, but a fork is the right setup for anything you plan to maintain.

2. Add your own skills and rules

The catalog lives in skills/, rules/, and plugins/ at the repo root. Drop in a directory with a metadata.yaml and a skill.md (or rule.md) and it shows up in the picker automatically. The authoring format is covered in detail below.

3. Run the CLI

From the root of any project you want to set up:

uvx --from git+https://github.com/<your-fork>/ai-agents-marketplace agents-marketplace

The TUI walks you through the rest:

1. Pick artifacts from the catalog (it shows installed status and available updates).
2. Review which AI tools were detected in your project and on your system.
3. Pick install targets — pre-checked based on that detection.
4. Confirm, and files are rendered and written into your project.
5. Optionally save your selection to agents-marketplace.yaml for team sync.

What actually gets written

This is the part that makes the “render many” claim concrete. A universal skill lands once per skill target; a single rule fans out across every agent format you selected:

Agents that read a single top-level instructions file — rather than auto-discovering a rules directory — get a reference injected idempotently, so it’s never duplicated on re-run: Claude rules append a note to .claude/CLAUDE.md or AGENTS.md, Codex appends to AGENTS.md, and Gemini appends to GEMINI.md (each created if missing). Cursor and Copilot auto-discover their directories, so they need no reference file.

Team sync

This is where the tool earns its keep on a team. Commit an agents-marketplace.yaml to your project root — think of it like VS Code’s .vscode/extensions.json — and every teammate gets the same agent setup after cloning, with no install step:

uvx --from git+https://github.com/aviz92/ai-agents-marketplace agents-marketplace sync

The manifest is small and readable:

# agents-marketplace.yaml
skills:
  - python-code-review
  - pre-push-checklist
rules: all                # 'all' installs every rule in the catalog
plugins: []
targets:                  # optional — defaults to detected agents
  skills: [claude, agents]
  rules: [cursor, claude]

A few details that matter in practice:

• skills / plugins / rules accept a list of artifact ids, or the string all.
• targets is optional — when omitted, sync installs to the agents it detects, falling back to .agents/skills plus all rule formats when nothing is detected.
• Unknown ids are reported and skipped; sync still installs the rest but exits non-zero so CI can catch drift. That last bit is what turns the manifest into a real guardrail rather than a suggestion.

The easiest way to produce the file is to run the interactive TUI once and answer yes to “Save installed state to agents-marketplace.yaml?” at the end. The saved manifest is a snapshot of everything currently installed — all targets, not just your latest selection — so re-saving never silently drops previously installed artifacts.

Authoring your own artifacts

The authoring format is deliberately boring, which is the point. A skill is a directory with two files:

# skills/<skill-id>/metadata.yaml
name: Human Readable Name
description: One-line description shown in the picker
tags: [optional, tags]
author: your-name
version: 1.0.0

<!-- skills/<skill-id>/skill.md -->
# What this skill does
Platform-agnostic markdown instructions...

It installs as <target>/<skill-id>/SKILL.md in every selected skill target. A skill can also bundle extra files — say assets/template.md — next to its skill.md; they’re copied as-is with relative paths preserved, so links like [template.md](assets/template.md) keep working after install. Plugins are identical, just under plugins/<plugin-id>/ with the body in plugin.md.

Rules add two metadata keys that the per-agent renderers consume:

# rules/<rule-id>/metadata.yaml
name: Human Readable Name
description: One-line description
tags: [optional]
author: your-name
version: 1.0.0
globs: ["src/**/*.py"]   # Cursor `globs` / Copilot `applyTo`
alwaysApply: true        # Cursor: rule is always active

That one authored rule produces the .mdc, .instructions.md, and three .md variants automatically.

Versioning that drives the update prompt

There’s no separate update database — versioning is baked into the rendered output. Bump version in metadata.yaml on any change, and because every rendered file embeds version: in its frontmatter, the CLI compares that field on the next run to decide whether to show ↻ Update or ✓ Installed. Simple, self-contained, and impossible to forget to wire up.

Why I built it

I maintain a growing set of reusable agent context — code-review skills, a pre-push checklist, Python and infrastructure rules — and I want the same guidance applied whether I’m in Claude Code on one machine or Cursor on another, and whether a teammate just cloned the repo or has been on it for months. Hand-syncing five formats doesn’t scale, and copy-paste drift quietly erodes the value of having written the rules at all.

ai-agents-marketplace makes the authored artifact the single source of truth and pushes the per-agent fragmentation down into a render step where it belongs. Author once, render many — and let a committed manifest plus a non-zero CI exit keep the whole team honest.

The project is on GitHub under an MIT license. uvx --from git+https://github.com/aviz92/ai-agents-marketplace agents-marketplace is the fastest way to try it.

Why I Built This

Most pytest projects accumulate module-level pytestmark lists over time. CI runs pytest -m regression — a generic command that touches the whole suite. That’s fine for most tests. But inside those modules there are always two or three tests that can only safely run under one specific marker condition. The existing options — move the file, add a skipif, change the module pytestmark, add -k exclusions to CI — are all bad for different reasons. I wanted the test itself to declare where it belongs, with the plugin enforcing it at collection time.

Installation

pip install pytest-only-markers

uv add pytest-only-markers

Setup & Configuration

[pytest]
addopts = --only-markers-prefix
markers =
    ONLY_smoke: Run only smoke tests
    ONLY_api: Run only API tests

Or pass the flag directly:

pytest --only-markers-prefix tests/

The plugin is opt-in — without --only-markers-prefix, all ONLY_* markers are inert and the suite runs normally.

Quick Start

Decorate the test that has constraints, run with the flag:

pytestmark = [pytest.mark.regression, pytest.mark.e2e]

def test_full_flow():
    ...

@pytest.mark.ONLY_smoke
def test_health_check():
    ...

pytest --only-markers-prefix tests/
# Only test_health_check runs. test_full_flow is deselected.
# pytestmark (regression, e2e) is stripped from test_health_check.

Real-World Example

Say your CI has two pipeline commands — a full regression suite and a fast smoke suite:

pytest -m regression          # full suite
pytest -m "smoke or ONLY_smoke"  # smoke suite

A module has tests that participate in regression, but one test should only ever run as part of smoke:

pytestmark = [pytest.mark.regression, pytest.mark.e2e]

def test_full_flow():
    ...

def test_checkout():
    ...

@pytest.mark.ONLY_smoke
def test_health_check():
    ...

With this setup:

ONLY_smoke does double duty: in CI it’s a scoped inclusion tag, locally it’s an isolation switch. No changes to pytest.ini. No -k hacks. No skipif conditions.

Key Features

When --only-markers-prefix is active and any test in the collected suite carries an ONLY_* marker, only those tests run. Everything else is deselected — appearing in pytest’s x deselected summary, never silently dropped. The plugin is transparent about what it’s doing.

Marker isolation is the part that makes this different from -k. Non-ONLY_* markers — including the entire module pytestmark — are stripped from matching tests at the item level. Downstream plugins, reporters, and hooks see only the ONLY_* markers for that test, giving you a genuinely clean execution environment. -k by contrast doesn’t strip inherited markers; it just filters by name.

The prefix match is case-insensitive — ONLY_smoke and only_smoke are treated identically, which matters on teams where engineers have different habits:

@pytest.mark.only_smoke   # lowercase — works
def test_ping():
    assert True

@pytest.mark.ONLY_smoke   # uppercase — equivalent
def test_pong():
    assert True

Stack multiple ONLY_* markers freely — all are preserved, everything else is stripped:

@pytest.mark.ONLY_api
@pytest.mark.ONLY_smoke
def test_create_user():
    assert True
# Effective markers: ONLY_api + ONLY_smoke
# pytestmark (regression, slow) stripped entirely

For local debugging loops, decorate the test you’re working on and iterate without touching CI config:

@pytest.mark.ONLY_debug
def test_payment_edge_case():
    ...

pytest --only-markers-prefix tests/payments/

Remove the decorator when you’re done — or leave it. Without --only-markers-prefix in CI’s addopts, the marker is inert.

Goes Well With

• custom-python-logger — the logger used in the examples; self.logger output flows into the report automatically
• pytest-plugins — CI reporting layer that works alongside the requirements manifest in pipeline workflows
• pytest-depends-on — run a specific dependency chain in isolation without triggering unrelated tests
• pytest-reporter-html — isolated runs produce tight, single-test HTML reports that are easy to share
• pytest-dynamic-parameterize — isolate one parameterized variant without running the full parameter set
• pytest-collect-requirements — collect test requirements from the same dynamic sources as your parameters for fully data-driven pipelines

Links

• PyPI: pypi.org/project/pytest-only-markers
• GitHub: github.com/aviz92/pytest-only-markers

Decorate the test. Run the flag. Everything else stays out of the way.

Why I Built This

I’ve built a lot of test infrastructure over the years — pytest plugins, CI integrations, custom reporters — and the one thing every team I’ve worked with has asked for eventually is a readable test report. The existing options were either too basic (pytest-html) or too heavy. Together with Yevgeny Farber, I built the reporter I actually wanted to use: fully interactive, zero code changes to get started, and structured around how test failures are actually debugged.

Installation

pip install pytest-reporter-html

uv add pytest-reporter-html

Quick Start

Add --report-html to your pytest options:

# pytest.ini
[pytest]
addopts =
    --report-html
    --output-dir=logs

After the run, open the report:

logs/test-reports/TestReport_Latest.html

No fixtures, no code changes, no config files to maintain. The plugin attaches to Python’s root logger automatically — every logging.*() call your tests already make is captured and surfaced in the report without any wiring.

Real-World Example

Here’s an API test with named steps. The report turns a flat log stream into a structured story about what the test actually did:

from custom_python_logger import get_logger
from pytest_reporter_html import step

logger = get_logger(__name__)

def test_user_lifecycle():
    with step("Create user"):
        logger.info("Creating a new user with role 'user'")
        response = api.post("/users", json={"role": "user"})
        assert response.status_code == 201

    with step("Update profile"):
        logger.info("Updating user's role to 'admin'")
        response = api.patch(f"/users/{user_id}", json={"role": "admin"})
        assert response.status_code == 200

    with step("Verify changes"):
        logger.info("Verifying that the role change persisted")
        response = api.get(f"/users/{user_id}")
        assert response.json()["role"] == "admin"

The report renders this as:

Test: test_user_lifecycle                                            PASSED
 ├── Step 01: Create user                               PASSED    120ms
 ├── Step 02: Update profile                            PASSED     45ms
 └── Step 03: Verify changes                            PASSED     30ms

When a step fails, the report auto-expands that test and highlights the failing step. The assertion message, stack trace, and every log event leading up to the failure are visible in context — no grepping through logs required.

Key Features

Zero-config log capture was a non-negotiable design decision. Every team already has logging in their tests. By attaching to the root logger, the plugin works with logging.info(...), custom_python_logger, structlog, or anything else that feeds the standard logging chain — no fixture swaps, no special calls.

Named steps are the main quality-of-life feature. The step context manager wraps any block of code into a collapsible, timed section in the report. Each step shows its duration and pass/fail status at a glance. Without manual steps, Setup, test body, and Teardown are created automatically for every test. step also works as a decorator — both sync and async:

@step("Fetch user data")
def get_user(user_id: str) -> dict:
    return api.get(f"/users/{user_id}").json()

@step("Send notification")
async def notify(user_id: str) -> None:
    await notification_service.send(user_id)

The HTML report ships with live search, status filters (Passed / Failed), and log-level filters (TRACE → ERROR) — all client-side, no server required. The report is a single self-contained file you can share via Slack, attach to a Jira ticket, or archive in S3 without deploying anything.

JSON content is syntax-highlighted inline. HTTP requests are rendered with a generated cURL command and copy button — which matters a lot when debugging API test failures and you want to reproduce a specific request outside the test.

Per-test JSON files are written alongside the HTML, one per test. If you want to post results to a dashboard, run a flakiness analysis, or build an alert on repeated failures, the structured JSON gives you the raw data independently of the HTML rendering. The report doesn’t have to be a dead end.

Goes Well With

• custom-python-logger — the logger used in the examples; self.logger output flows into the report automatically
• pytest-plugins — CI reporting layer that works alongside the requirements manifest in pipeline workflows
• pytest-depends-on — run a specific dependency chain in isolation without triggering unrelated tests
• pytest-reporter-html — isolated runs produce tight, single-test HTML reports that are easy to share
• pytest-dynamic-parameterize — isolate one parameterized variant without running the full parameter set
• pytest-collect-requirements — collect test requirements from the same dynamic sources as your parameters for fully data-driven pipelines

Links

• PyPI: pypi.org/project/pytest-reporter-html
• GitHub: github.com/YevgenyFarber/pytest-reporter-html

Built together with Yevgeny Farber. If your team is still debugging CI failures from terminal output, this is the upgrade.

The Foundation: dev-template-repository

Everything starts from dev-template-repository — my main base template. It’s not a starter for a specific type of project; it’s the skeleton every project starts from, regardless of what it does. Pre-commit hooks, CI workflows, IDE config, env.template, Go-Task commands, CODEOWNERS — all wired up before a single line of business logic is written.

I covered it in detail in How I Structure Python Projects. Read that first if you haven’t.

The specialized templates below all build on top of this foundation. They inherit the base structure and add the domain-specific decisions on top.

The Philosophy

A template isn’t documentation. It’s a frozen set of opinions you don’t have to revisit. When I clone a template, I’m not asking “how should I structure this?” — that question was answered when the template was built. I’m asking “what am I building?”

Each template here is production-ready on day one: pre-commit hooks, structured logging via custom-python-logger, environment variable configuration, and a working example you can run immediately.

A Few Examples

FastAPI Template

The FastAPI starter comes with authentication wired up out of the box — register, login, JWT token issuance, and a protected route. Most FastAPI projects need this eventually and it’s always the same boilerplate.

Clone it, delete the example routes, and start on your actual endpoints.

→ github.com/aviz92/fast-api-template

Django Basic App

Built on top of drf-easy-crud and django-versioned-models — the same packages I covered in earlier posts. You get enterprise-grade CRUD with advanced filtering, pagination, bulk operations, and versioned data models without wiring any of it up yourself.

The interesting part: most Django projects end up needing all of these within the first few weeks. Starting with them already in place means you’re building features on a solid foundation from day one, not retrofitting infrastructure later.

→ github.com/aviz92/django-basic-app

Docker MCP Service Template

The most recent addition. As AI coding agents have become part of daily development, the ability to expose custom tools to them via the Model Context Protocol has become genuinely useful. This template gives you a Dockerized MCP server with a service layer pattern — add a class to mcp_services/, register a tool in server.py, and your logic is immediately available to Claude Desktop or any MCP-compatible client.

@mcp.tool()
async def get_deployment_status(service_name: str) -> str:
    return await DeploymentService.get_status(service_name)

That’s all you add. The rest — server lifecycle, Docker build, Claude Desktop config — is already handled.

→ github.com/aviz92/docker-mcp-service-template

A Note on ai-agents-marketplace

ai-agents-marketplace deserves a mention here even though it’s not a project template in the traditional sense. It’s a CLI that distributes reusable AI-agent context — skills, plugins, and rules — into any project, rendering each artifact into the native format every supported coding agent expects.

The reason it belongs in this section: if you’re building a project and want AI coding agents to have proper context about your codebase, you’d run agents-marketplace after cloning your template. It’s the last step of the setup flow.

One important usage note: fork the repo before running it in a project you plan to maintain long-term. The marketplace ships with a curated set of skills and rules, and new ones get added over time. If you fork it, you can pull upstream changes to get new features while keeping any customizations you’ve made to the rules for your specific project. Running directly from the original repo works fine for a quick setup, but a fork gives you the ability to sync selectively as the marketplace evolves.

→ github.com/aviz92/ai-agents-marketplace

The Full Collection

The templates above are examples from a growing set. There are also starters for Telegram bots, Slack bots, and more being added over time. Rather than maintain an exhaustive list here that goes stale, the current full collection lives on GitHub:

→ github.com/aviz92

Each repo is a GitHub template — hit Use this template and you have a new repository with the full starter, ready to clone.

I needed email notifications in several automation scripts: pipeline failures, scheduled report delivery, monitoring alerts. The code was always the same fifteen lines. So I packaged it.

Why I Built This

The Python smtplib + email.mime stack works fine but it’s verbose for something conceptually simple. You want to send an email — you shouldn’t need to construct a MIME tree to do it. python-simple-email-sender reduces it to one call with sensible defaults.

Installation

pip install python-simple-email-sender

uv add python-simple-email-sender

Setup

Credentials come from environment variables — no hardcoded passwords:

export EMAIL_ADDRESS="your.email@gmail.com"
export EMAIL_PASSWORD="your-app-password"

For Gmail, use an App Password rather than your account password if you have 2FA enabled. Generate one at myaccount.google.com/apppasswords.

Usage

from python_simple_email_sender import EmailSender

sender = EmailSender()

sender.send_email(
    to_email=["team@company.com"],
    subject="Nightly pipeline complete",
    message="All 1,204 tests passed. Report attached.",
    attachment_file="reports/nightly.pdf"
)

That’s the whole interface. to_email accepts a string or a list. attachment_file is optional. Credentials are picked up from the environment automatically.

For a non-Gmail SMTP server, pass server_name and server_port:

sender = EmailSender(server_name="smtp.company.com", server_port=587)

Real-World Use Case

In CI pipelines and scheduled automation scripts, email is often the simplest reliable notification channel — no Slack bot to configure, no webhook endpoint to maintain. Here’s how I use it for a nightly report script:

from python_simple_email_sender import EmailSender

def send_nightly_report(report_path: str, recipients: list[str]) -> None:
    sender = EmailSender()
    sender.send_email(
        to_email=recipients,
        subject="[Nightly] Infrastructure Health Report",
        message="Automated report attached. Contact the infra team for questions.",
        attachment_file=report_path,
    )

One function, one import, works anywhere Python runs.

Links

• PyPI: pypi.org/project/python-simple-email-sender
• GitHub: github.com/aviz92/python-simple-email-sender

If you’ve typed MIMEMultipart() more than twice in your life, you don’t need to type it again.

Why I Built This

I wanted re-recording to be as simple as running a single command, with the same structure and output every time. The issue isn’t the recording tool — asciinema is great. The issue is that the recording is a manual, ad-hoc session that nobody remembers how to reproduce. I wanted to commit the demo script alongside the code so that re-recording after a release is one command, not a half-hour of typing into a terminal hoping it looks right.

Installation

pip install cast-studio

uv add cast-studio

Requires ffmpeg installed on the system.

Quick Start

Three commands from zero to GIF:

# 1. Scaffold the demo config into your project
cast-init --dest demo/

# 2. Record the session driven by your config
asciinema rec -c "cast-run demo/demo.cfg" assets/demo/demo.cast

# 3. Render to GIF (or MP4)
cast-render assets/demo/demo.cast assets/demo/demo --gif-only --title "my-library demo"
# → assets/demo/demo.gif

Real-World Example

Here’s the demo.cfg for cast-studio itself — the config that drives its own demo recording:

# ── project metadata ──────────────────────────────────────────────────────────
PROJECT="cast-studio"
SUBTITLE="Convert asciinema .cast files to GIF and MP4"
INSTALL_CMD="uv add cast-studio"
REPO_URL="github.com/aviz92/cast-studio"
PYPI_URL="pypi.org/project/cast-studio"

# ── timing (seconds) ─────────────────────────────────────────────────────────
PAUSE_INTRO=2
PAUSE_BETWEEN=2
PAUSE_OUTRO=3

# ── runs ──────────────────────────────────────────────────────────────────────
define_runs() {
  add_run \
    "STEP 1 — cast-init  │  scaffold demo scripts into your project" \
    "Creates run_demo.sh (the engine) and demo.cfg (your project config).|One command sets up the full demo recording workflow." \
    "cast-init --dest /tmp/cast-studio-demo --force"

  add_run \
    "STEP 2 — demo.cfg  │  inspect the generated config" \
    "Edit PROJECT, SUBTITLE, INSTALL_CMD, and define_runs().|Add any shell command — pytest, scripts, CLIs — using add_run." \
    "cat /tmp/cast-studio-demo/demo.cfg"

  add_run \
    "STEP 3 — cast-render  │  render a .cast file to GIF" \
    "Renders each frame as a PNG using Pillow (Catppuccin Mocha theme).|Then encodes a high-quality 256-colour GIF via ffmpeg palette pass." \
    "cast-render demo.cast assets/demo --gif-only --title \"cast-studio demo\""

  add_run \
    "STEP 4 — cast-render  │  render to MP4" \
    "H.264/x264 CRF-18 encode — ready for GitHub Releases or Twitter.|Use --hold to extend the last frame so viewers can read the outro." \
    "cast-render demo.cast assets/demo --mp4-only --hold 5.0 --title \"cast-studio demo\""
}

You commit demo.cfg alongside your code. After the next release, re-recording is:

asciinema rec -c "cast-run demo/demo.cfg" assets/demo/demo.cast
cast-render assets/demo/demo.cast assets/demo/demo --gif-only --title "my-library demo"

Same config. Same structure. Updated output.

Key Features

The demo engine is the core idea. demo.cfg is a shell file that defines every step of your terminal session — what command to run, what title and description to display, how long to pause between steps. cast-run executes it to drive the asciinema recording. The session isn’t typed manually; it’s scripted and repeatable. Each add_run call adds one step, and multi-line descriptions use | as a separator.

cast-init scaffolds demo.cfg and the runner script into any project with one command — so adding a reproducible demo to an existing package takes minutes, not an afternoon.

The rendering pipeline produces two formats. GIFs use Pillow to render each frame as a PNG with a custom ANSI terminal emulator and the Catppuccin Mocha color scheme, then encode through a two-pass ffmpeg palette for sharp 256-colour output. MP4 is H.264 CRF-18 — high quality, small file, ready for GitHub Releases, Notion, or Slack. Both formats are driven by the same .cast file.

# GIF — default 10 fps, sharp and compact
cast-render demo.cast assets/demo --gif-only --title "my-library demo"

# MP4 — default 30 fps, hold last frame for 5 seconds
cast-render demo.cast assets/demo --mp4-only --hold 5.0 --title "my-library demo"

The cast unified entry point auto-discovers all sub-commands — cast render, cast init, cast --help — one entry point for everything.

If you just need a quick one-off GIF and don’t care about reproducibility, agg is simpler. cast-studio is for demos that need to stay accurate across releases.

Goes Well With

• python-base-command — the CLI pattern I use in the libraries that get demoed with this tool
• custom-python-logger — colored terminal output that looks great in recordings

Links

• PyPI: pypi.org/project/cast-studio
• GitHub: github.com/aviz92/cast-studio

A demo that lives in the repo gets updated. One that lives in someone’s terminal history doesn’t.

django-versioned-models packages that pattern into a single mixin. Inherit from VersionedModel, run a migration, and your models get full release management, a three-stage data-status workflow, and CI-ready management commands — automatically.

Installation

pip install django-versioned-models

uv add django-versioned-models

# settings.py
INSTALLED_APPS = [
    ...
    'django_versioned_models',
]

python manage.py migrate

Quick Start

from django_versioned_models.mixins import VersionedModel

class Product(VersionedModel):
    name = models.CharField(max_length=255)

    class Meta:
        unique_together = [('release', 'name')]  # unique per release, not globally

python manage.py makemigrations && python manage.py migrate

python manage.py create_release --release-version v1.0.0
# → add data via Admin or API
python manage.py lock_release --release-version v1.0.0

The Core: Three Fields, One Workflow

Every model that inherits from VersionedModel gets three fields added automatically:

• release — FK to a Release record. Every row belongs to exactly one release.
• status — the data-readiness stage: DRAFT, FUTURE, or APPROVED.
• active — soft-delete flag (covered below).

The release and status fields together are the heart of the system.

The Three-Status Workflow

DRAFT  <-->  FUTURE  -->  APPROVED

The transition rules enforce the intended workflow:

• DRAFT → FUTURE via mark_future() — user parks the row for a later cycle
• FUTURE → DRAFT via mark_draft() — user pulls it back for rework
• DRAFT or FUTURE → APPROVED via approve() — one-way, CI only

APPROVED is a terminal state. There is no transition back. If a row needs to change after approval, the correct action is to create a new release (or a patch release) and update the row there.

Why Three Statuses?

Two statuses (DRAFT / APPROVED) are enough for a single sprint, but they break down as soon as users are working across multiple future cycles at the same time. FUTURE gives them a holding area for rows that are correct and intentional but shouldn’t be approved yet — without mixing them up with rows that are still actively being worked on (DRAFT).

Status Transitions in Code

row.mark_future()  # DRAFT → FUTURE
row.mark_draft()   # FUTURE → DRAFT
row.approve()      # DRAFT or FUTURE → APPROVED (one-way, CI only)

Querying by Status

from django_versioned_models.models import Release

release = Release.objects.get(version='v1.1.0')

Product.objects.approved(release)                        # CI — APPROVED rows only
Product.objects.for_release(release)                     # all rows for users
Product.objects.filter(release=release, status='future') # just the parked rows

The Release Lifecycle

Releases are the outer container. Every row belongs to a release. Releases move through their own lifecycle independently of individual rows:

# 1. Branch from the last locked release
python manage.py create_release --release-version v1.1.0 --based-on v1.0.0

# 2. users edit data in DRAFT. Park anything not ready in FUTURE.

# 3. CI approves all DRAFT rows (FUTURE rows are intentionally left alone)
python manage.py approve_release --release-version v1.1.0

# 4. Run tests against approved data only
pytest --release-version v1.1.0

# 5. Lock and ship
python manage.py lock_release --release-version v1.1.0

# 6. Bug found after deployment? Always patch — never touch a locked release
python manage.py create_release --release-version v1.1.1 --based-on v1.1.0

The separation between FUTURE rows and approve_release is deliberate: bulk approval only touches DRAFT rows. FUTURE rows are not accidentally approved when CI runs approve_release — users have to explicitly mark_draft() them first.

Lock Enforcement

Locked releases are immutable at the model level. Any save() or delete() call on a row in a locked release raises ValidationError — from the Admin, the API, or the shell.

# Both raise ValidationError if release is locked
product.save()
product.delete()

This is enforced in VersionedModel.save() and VersionedModel.delete() — there is no way to bypass it in application code. If a row needs to change after locking, the answer is always a new patch release branched from the locked one.

The active Field — Soft Deletion That Respects the Status Workflow

On top of the three-status system, each row also carries an active flag. This is a soft-delete mechanism, but it is integrated with the status workflow rather than being independent from it.

The key rule: deactivating a row that was APPROVED resets its status back to DRAFT.

deactivate()  →  active=False,  status → DRAFT  (if it was APPROVED)
reactivate()  →  active=True,   status stays DRAFT

CI only runs against rows where status=APPROVED AND active=True.

product.deactivate()
# Before: active=True,  status="approved"
# After:  active=False, status="draft"   ← CI can no longer see it

product.reactivate()
# After:  active=True,  status="draft"   ← visible to users, not yet to CI
# Must go through approve() again before CI sees it

You cannot change the status of an inactive row — all transition methods (mark_future, mark_draft, approve) raise ValidationError if active=False. You must reactivate() first.

When a new release is branched from a locked one, inactive rows are carried over too. This preserves the historical record and lets users choose to reactivate() a soft-deleted row in the new release if the need arises.

Auto-Discovery and Topological Copy

When create_release --based-on runs, it discovers all models that inherit from VersionedModel automatically — no manual registration. FK dependencies between those models are resolved via topological sort, so models are copied in the correct order. No ordering required on the developer’s part.

Management Commands Reference

Goes Well With

• custom-python-logger — logging I wire up alongside the client for request tracing
• drf-easy-crud — the DRF API layer on the server side that pyrest-model-client talks to in my projects
• django-versioned-models — versioned model queries I consume through this client

Links

• PyPI: django-versioned-models
• GitHub: aviz92/django-versioned-models

Feedback, issues, and PRs are welcome.

The Foundation: Start From a Template

Every project I start comes from dev-template-repository — a GitHub template that wires up everything before I write a single line of business logic:

my-project/
├── .github/
│   ├── workflows/
│   │   └── publish_to_pypi.yml     # automated PyPI publishing
│   ├── CODEOWNERS                  # default reviewers per path
│   ├── ISSUE_TEMPLATE/             # bug reports, feature requests
│   └── pull_request_template.md    # contribution checklist
├── .vscode/
│   ├── settings.json               # format on save, lint integration
│   ├── extensions.json             # recommended extensions
│   └── launch.json                 # debug configurations
├── .cursor/                        # Cursor IDE config
├── requirements.txt
├── MANIFEST.in
├── env.template                    # .env structure, committed to git
├── Taskfile.yml                    # Go-Task for common dev commands
├── .pre-commit-config.yaml         # Black, Ruff, Pylint
├── CHANGELOG.md
├── LICENSE
└── README.md

Key decisions baked in:

• Pre-commit hooks (Black + Ruff + Pylint) run on every git commit. Code style is never a PR discussion.
• env.template is committed. .env is gitignored. New team members know exactly what variables to fill in.
• Go-Task standardizes task lint, task test, task build across every project.
• CODEOWNERS means the right person gets tagged on every PR automatically.

Setup takes 5 minutes:

git clone https://github.com/aviz92/my-new-project.git
cd my-new-project
uv venv && source .venv/bin/activate
uv sync
cp env.template .env
pre-commit install

Logging: One Call, Everywhere

Every project uses custom-python-logger — configured once at the entry point, then imported wherever needed:

# main.py or app.py
from custom_python_logger import build_logger

logger = build_logger(
    project_name='my-project',
    log_file=True,
    utc=True,
    extra={'env': 'production'}
)

# anywhere else in the codebase
from custom_python_logger import get_logger

logger = get_logger('my-module')
logger.step("Starting phase 2...")   # custom level for pipeline steps
logger.info("Connected to DB")
logger.exception("Failed to parse response")

Two custom levels that I use constantly:

• STEP — marks a named phase in a pipeline. Makes logs scannable at a glance.
• EXCEPTION — dedicated level for caught exceptions, separate from ERROR. Easy to grep in production.

CLI Tools: Django-Style Without Django

When a project needs a CLI — scripts, automation tools, data pipelines — I use python-base-command.

The pattern is identical to Django management commands, but with zero Django dependency:

my-project/
├── cli.py              # 2-line entry point
└── commands/
    ├── __init__.py
    ├── sync.py
    ├── export.py
    └── validate.py

# cli.py
from python_base_command import Runner
Runner(commands_dir="commands").run()

# commands/sync.py
from python_base_command import BaseCommand, CommandError

class Command(BaseCommand):
    help = "Sync data from upstream source"
    version = "1.0.0"

    def add_arguments(self, parser):
        parser.add_argument("--env", choices=["staging", "prod"], required=True)
        parser.add_argument("--dry-run", action="store_true")

    def handle(self, **kwargs):
        if kwargs["dry_run"]:
            self.logger.warning("Dry run — no changes written.")
            return

        self.logger.step("Connecting to upstream...")
        # logic here
        self.logger.info(f"Sync complete for env={kwargs['env']}")

python3 cli.py --help
python3 cli.py sync --env staging --dry-run
python3 cli.py export --format json

Every command gets --version, --verbosity, --traceback for free. self.logger is wired up automatically. Testing uses call_command() — identical to Django.

REST API: Two Templates for Two Use Cases

Django REST Framework — Data-Heavy APIs

For APIs that need versioned data, complex filtering, or admin interfaces: django-basic-app.

Out of the box it includes:

• CRUDUtils — one static class handles all five CRUD operations with wildcard filtering, pagination, and FK lookups
• VersionedModel — every model participates in release management automatically
• Data status workflow — DRAFT → FUTURE → APPROVED, where CI always queries approved data

# One mixin, full versioning
class MyModel(VersionedModel):
    name = models.CharField(max_length=255)
    # That's it. Versioned, locked, auto-discovered.

The CI flow:

create_release → architects edit data → approve_release → run tests → lock_release

FastAPI — Lightweight Services

For simpler services, microservices, or prototypes: fast-api-template.

Pre-configured with JWT authentication, SQLite (swappable), and example routes ready to extend.

git clone https://github.com/aviz92/fast-api-template.git
cd fast-api-template
uv sync
uv run uvicorn main:app --reload
# → http://localhost:8000/docs

MCP Services: AI Tool Integration

For projects that expose tools to LLMs (Claude Desktop, etc.): docker-mcp-service-template.

The pattern: a FastMCP server + service layer + Docker:

mcp-service/
├── server.py           # MCP tool definitions
├── mcp_services/
│   ├── weather.py      # business logic, separate from MCP layer
│   └── ping.py
├── Dockerfile
└── .env

# server.py
@mcp.tool()
def get_weather(city: str) -> dict:
    """Fetch current weather for a given city."""
    return weather_service.fetch_weather(city)

// Claude Desktop config
{
  "mcpServers": {
    "my-service": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "my-mcp-service"]
    }
  }
}

Business logic stays in service classes. MCP tool definitions stay thin. Adding a new tool means adding one service file and registering one decorator.

The Full Picture

Here’s how the layers stack across a typical project:

┌─────────────────────────────────────────┐
│         dev-template-repository          │  base structure, CI, pre-commit
├─────────────────────────────────────────┤
│         custom-python-logger             │  logging everywhere
├─────────────────────────────────────────┤
│         python-base-command              │  CLI tools and scripts
├─────────────────────────────────────────┤
│    django-basic-app / fast-api-template  │  API layer
├─────────────────────────────────────────┤
│         docker-mcp-service-template      │  LLM tool exposure (if needed)
└─────────────────────────────────────────┘

Every layer is optional — a simple automation script might only use the base template and the logger. A full data platform uses all of them.

What This Gives You

• Zero setup time — clone the template and you have CI, linting, and pre-commit from minute one
• Consistent structure — any project looks familiar to anyone on the team
• Opinionated defaults — you don’t decide formatting style on every PR
• Testable by design — call_command() for CLI, standard pytest for APIs
• Production logging from day one — no print() debugging that leaks into production

The templates are all open source and available on GitHub. Clone any of them, use the template button, or just steal the patterns that work for you.

Related Posts

• drf-easy-crud: Enterprise-Grade CRUD for Django REST Framework
• custom-python-logger: Colored, Contextual Logging for Python Projects
• python-base-command: Django-Style CLI Commands Without Django
• django-versioned-models: Drop-in Release Management for Django Models

Why I Built This

I wanted to see how far structured LLM output could go in a real support workflow. Not a chatbot that gives vague answers — something that commits to a category, an urgency level, a confidence score, and an actual response, all in a validated Pydantic schema. Slack was the right channel because that’s where support requests actually land. The result is something you can drop into an existing support workflow and start getting AI-classified tickets immediately.

Installation

git clone https://github.com/aviz92/ticket-assist.git
cd ticket-assist
uv sync

Setup & Configuration

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_SIGNING_SECRET=your-signing-secret
SLACK_BOT_USER_ID=U0XXXXXXXXX

LLM_PROVIDER=claude          # options: claude | gemini | openai
ANTHROPIC_API_KEY=your-anthropic-key
GEMINI_API_KEY=your-gemini-key
OPENAI_API_KEY=your-openai-key

Switch providers with a single env var — no code changes:

Quick Start

# 1. Install dependencies
uv sync

# 2. Configure environment
cp .env.example .env

# 3. Get your bot user ID
uv run python slack_bot/user_id.py

# 4. Start the Flask server
uv run python -m slack_bot.app

# 5. Expose with ngrok
ngrok http 5000

Set https://<your-ngrok-url>/slack/events as the Event Subscriptions URL in your Slack app settings, then invite the bot to a channel with /invite @YourBotName.

Real-World Example

A customer messages in Slack: @ticket-assist My order #12345 hasn't arrived yet and I needed it for an event tomorrow.

The bot runs the classification pipeline and replies immediately:

response.category    # TicketCategory.ORDER_ISSUE
response.urgency     # TicketUrgency.HIGH
response.sentiment   # "frustrated, time-sensitive"
response.confidence  # 0.94
response.ticket_complete  # True
response.answer      # "I'm sorry to hear your order hasn't arrived..."

The answer field contains a ready-to-send customer reply — the support agent can post it directly or edit it first. Category, urgency, and sentiment give the team everything they need to route and prioritize without reading the full message.

Key Features

The core of the bot is a Pydantic schema that defines exactly what the LLM must return. There’s no parsing, no brittle string matching — the model either returns a valid TicketClassification or the request retries up to three times:

response = llm.completions_create(
    response_model=TicketClassification,
    temperature=0,
    max_retries=3,
    messages=[
        {"role": "system", "content": SYSTEM_PROMPT},
        {"role": "user", "content": user_input},
    ],
)

Using Pydantic as the response model means every field is typed and validated before the bot replies. A classification without a confidence score or a missing urgency level is caught before it reaches the user — not after.

The event handling is minimal by design. Built on Slack Bolt and Flask, the bot exposes a /slack/events webhook that receives app_mention events. When mentioned, it strips the mention tag, runs the AI pipeline, and calls say() with the generated answer:

@app.event("app_mention")
def handle_mentions(body: dict[str, Any], say: Say) -> None:
    text = body["event"]["text"].replace(f"<@{SLACK_BOT_USER_ID}>", "").strip()
    say("thinking...")
    response = ai_function(llm=llm, user_input=text)
    say(response.answer)

Multi-LLM support lets you swap providers without touching the classification logic. temperature=0 keeps responses deterministic regardless of which model is behind it.

Goes Well With

• python-jira-plus — create a Jira ticket automatically from the classification output
• python-vault — store Slack and LLM API tokens in Vault instead of plain env vars
• custom-python-logger — structured logging for every classification event and LLM call

Links

• GitHub: github.com/aviz92/ticket-assist

Mention the bot. Get a classification. Route the ticket. Done.

Why I Built This

I kept losing thoughts. Not because I wasn’t writing them down — I was, in five different places. A notes app, a Telegram draft, a napkin, a sticky note on the monitor. None of it was searchable later and none of it was organized. I wanted one place where everything landed automatically, with the AI doing the classification and summarization I never got around to doing manually. Notion was already where I worked. Telegram was already on my phone. I just needed something to connect them.

Installation

git clone https://github.com/aviz92/think-drop.git
cd think-drop
uv sync

Or with Docker:

docker-compose up --build -d

Setup & Configuration

Create a .env file with your credentials:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token

NOTION_TOKEN=your_notion_internal_integration_secret
NOTION_DB_ID=your_notion_database_id

LLM_PROVIDER=gemini          # options: gemini | openai | claude
GEMINI_API_KEY=your_gemini_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_key

Only the API key for your chosen provider is required. Switch providers by changing LLM_PROVIDER — no code changes:

Create a Notion database with these properties and connect your integration:

Quick Start

# 1. Clone and install
git clone https://github.com/aviz92/think-drop.git
cd think-drop
uv sync

# 2. Configure
cp .env.example .env  # fill in your credentials

# 3. Run
uv run python think_drop/main.py

Open Telegram, find your bot, send /start.

Real-World Example

Send “remind me to buy a birthday gift for Sarah next week” and here’s what happens end-to-end:

INFO  [a3f2c1b8] Message received | user_id=123456 username=avi | chars=51
INFO  [a3f2c1b8] LLM classification started | provider=gemini
DEBUG [a3f2c1b8] LLM response received | response_chars=98
INFO  [a3f2c1b8] LLM classification done | title='Gift for Sarah' category=Shopping
INFO  [a3f2c1b8] Notion write started | title='Gift for Sarah' category=Shopping
INFO  [a3f2c1b8] Note saved to Notion | url=https://notion.so/abc123...
INFO  [a3f2c1b8] Confirmation sent to user

Your Notion database gets a new row: title Gift for Sarah, category Shopping, raw text preserved, summary generated, date stamped. Every incoming message gets a unique 8-character session ID so the full pipeline is traceable in logs from receive to confirmation.

Key Features

The pipeline is fully automatic — there’s nothing to configure per-note. Send a message, the AI classifies it into one of eight categories (Work, Home, Ideas, Shopping, Meetings, Reading, Decisions, Personal), generates a title and summary, and writes it to Notion with full metadata. The raw text is preserved alongside the summary so nothing is lost.

Multi-LLM support means you’re not locked to one provider. LLM_PROVIDER=gemini today, LLM_PROVIDER=claude tomorrow — the pipeline is identical. Useful when you want to compare output quality or when a provider has an outage.

Session-scoped log tracing gives every incoming message a unique 8-character ID shared across all log lines for that request. When something goes wrong — a failed Notion write, a malformed LLM response — you can grep for the session ID and see the exact sequence of events, with no log lines from other concurrent messages mixed in.

Async processing keeps the bot responsive under load. Each message is processed asynchronously so a slow LLM response on one note doesn’t block others.

Goes Well With

• python-notion-plus — the Notion client layer under the hood
• python-vault — store Telegram and Notion tokens in Vault instead of a plain .env
• custom-python-logger — the logger powering session-scoped tracing

Links

• GitHub: github.com/aviz92/think-drop

One Telegram message. One Notion row. Zero friction.