Skip to content

Zenith

Zenith Emblem

An opinionated template for modern Python 3.12+ services, packages, and autonomous AI agents.

Note

What Zenith Is: Zenith is a production-grade Cookiecutter project template for Python 3.12+. Rather than a runtime library you import, it scaffolds a complete, pre-configured repository with sub-second developer tooling and autonomous AI agent workflowsβ€”so you can write production code from commit zero without tooling debt.

Human-First, AI-Accelerated: Zenith works identically as a pure human-driven developer workflow. All AI tooling and agent skills are 100% elective during scaffolding. The strict quality gatesβ€”100% test coverage, strict typing, complexity limits, and layer boundariesβ€”help human developers just as much as AI agents by providing instant feedback, fearless refactoring, and zero review bikeshedding.

Quick Start

Tip

Prerequisites & First Steps Zenith requires Astral uv. If you do not have uv installed yet:

curl -LsSf https://astral.sh/uv/install.sh | sh

If terms like virtual environments, uv, or project scaffolding are unfamiliar, start with the First Steps & Core Concepts guide.

Scaffold a production-grade repository in seconds using uvx:

$ uvx cookiecutter https://github.com/bwrob/zenith.git
$ cd my-awesome-service
$ uv sync
$ uv run poe test
100% test coverage reached (statements and branches).
$ uv run poe code-quality
All quality gates passed!
$ uv run poe docs-serve
Serving documentation at http://127.0.0.1:8000

The Four Pillars

Zenith eliminates scaffolding debt and quality decay from commit zero across four foundational pillars:

  • Modern Rust-Based Tooling


    Sub-second developer loops powered by uv, Ruff, Pyrefly, Tach, Deptry, complexipy, and Zensical. All tasks run through Poe the Poet for identical local and CI execution.

  • First-Class AI Agent Readiness


    Built for autonomous pair-programming when desired, yet completely elective. Scaffold all assistants, select your preferred tools, or exclude AI configs entirely for a traditional Python repository. Audited in the Agentic Tool Matrix.

  • Automated Quality Guardrails


    Rigor that accelerates humans and agents alike: 100% mandatory test coverage (fail_under = 100), strict static typing with Pyrefly, cognitive complexity limits (<= 10), module boundary enforcement, and CI security auditing.

  • Hermetic Delivery & CI/CD


    Zero-drift automation: multi-version matrix testing across Python 3.12–3.15, isolated wheel package smoke tests, automated documentation publishing, and PyPI Trusted Publishing with supply-chain safeguards.

Architecture at a Glance

Scaffolded projects enforce strict separation between domain logic, public interfaces, and automated quality guardrails:

πŸ“ my-awesome-service/
β”œβ”€β”€ πŸ“ src/my_awesome_service/     # Core package source, public API, and optional Typer CLI
β”œβ”€β”€ πŸ“ tests/                      # Comprehensive test suite with 100% coverage gate
β”œβ”€β”€ πŸ“ docs/                       # Zensical documentation site with live preview
β”œβ”€β”€ πŸ“ .agents/skills/             # Modular agent skills (workflows, tools, style guides)
β”œβ”€β”€ TOML pyproject.toml              # Dependencies and packaging standards (PEP 621)
β”œβ”€β”€ TOML poe_tasks.toml              # Hermetic task runner commands (Poe the Poet)
└── Markdown AGENTS.md                   # Canonical AI agent instructions and boundary rules

Production-Grade Code by Default

Every generated repository produces strictly typed, immutable, and fully tested Python out of the box:

"""Core domain logic with strict typing and immutability."""

from dataclasses import dataclass


@dataclass(frozen=True, slots=True)
class Greeter:
    """Greeting domain entity."""

    recipient: str

    def format(self) -> str:
        """Format greeting with recipient."""
        return f"Hello, {self.recipient}!"
"""Command line interface powered by Typer and Rich."""

from typing import Annotated

import typer
from my_awesome_service.core import Greeter
from rich.console import Console

app = typer.Typer(no_args_is_help=True)
console = Console()


@app.command()
def greet(
    name: Annotated[str, typer.Argument(help="Name to greet.")] = "World",
) -> None:
    """Display a personalized greeting."""
    greeter = Greeter(recipient=name)
    console.print(f"[bold green]✨ {greeter.format()}[/bold green]")
"""Automated CLI test suite with 100% coverage gate."""

from my_awesome_service.cli import app
from typer.testing import CliRunner

runner = CliRunner()


def test_greet() -> None:
    result = runner.invoke(app, ["greet", "Zenith"])
    assert result.exit_code == 0
    assert "✨ Hello, Zenith!" in result.stdout

Tip

Explore the Live Showcase Repository

Browse instantiated code, commit history, and GitHub Actions runs in bwrob/zenith-example on GitHub. For release notes and version history, see the Changelog.