Zenith¶
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:
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:
The Four Pillars¶
Zenith eliminates scaffolding debt and quality decay from commit zero across four foundational pillars:
-
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.
-
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. -
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)
βββ pyproject.toml # Dependencies and packaging standards (PEP 621)
βββ poe_tasks.toml # Hermetic task runner commands (Poe the Poet)
βββ 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.