ZodiacCore-Py

Stop copy-pasting your FastAPI infrastructure.

An opinionated, async-first core library, CLI, and agent-ready quality loop.

🎯 Mission

Stop copy-pasting your infrastructure code.

Every new FastAPI project starts the same way: setting up logging, error handling, database sessions, pagination... It's tedious, error-prone, and inconsistent across teams.

ZodiacCore solves this in three ways: a library you drop into any FastAPI app, a CLI that scaffolds a full project in seconds, and a quality loop so you — or your coding agent — build on it correctly.

✨ Key Features

• 🔍 Observability First: Built-in JSON structured logging with Trace ID injection across the entire request lifecycle (Middleware → Context → Log).
• 🛡️ Robust Error Handling: Centralized exception handlers that map ZodiacException to standard HTTP 4xx/5xx JSON responses.
• 💾 Database Abstraction: Async SQLAlchemy session management and BaseSQLRepository with pagination helpers (paginate_query).
• 🎁 Standard Response Wrapper: Automatic wrapping of API responses into code / data / message via APIRouter.
• 📄 Standard Pagination: PageParams and PagedResponse[T] with repository integration.
• ⚡ Async Ready: Python 3.12–3.15 async/await from the ground up.
• ⌨️ zodiac CLI: Scaffold a 3-tier FastAPI project (DI, routers, config) with one command.
• 🔎 Wiring Checks: zodiac check AST-scans services for envelope, exception, session, HTTP, and middleware wiring anti-patterns.
• 🧩 Developer Skills: Version-matched docs and adoption audits ship in the wheel, linked with zodiac skills install.

📦 Quick Install

Extras (combinable): zodiac-core[sql] (SQLModel), zodiac-core[mongo] (Motor, helpers planned), zodiac-core[cache] (aiocache), zodiac-core[zodiac] (CLI). See the Installation Guide for details.

🚀 Ways to use ZodiacCore

1. Scaffolding (fastest start)

Use the zodiac CLI to generate a full project: 3-tier architecture, dependency injection, config, and tests.

Note: dfd-service below is the name of the new project you want to create; replace it with your own.

mkdir dfd-service
cd dfd-service
uv init --python 3.12

uv add "zodiac-core[zodiac,sql]"
zodiac new dfd-service --tpl standard-3tier -o .. --force

uv add "fastapi[standard]" --dev
uv run zodiac skills install
uv run zodiac check
uv run fastapi run --reload

Open http://127.0.0.1:8000/docs and http://127.0.0.1:8000/api/v1/health. See Getting started and CLI docs.

2. Library (use in your own app)

Add zodiac-core to an existing FastAPI project and wire up logging, middleware, and response wrapping.

from fastapi import FastAPI
from loguru import logger
from zodiac_core.exception_handlers import register_exception_handlers
from zodiac_core.exceptions import NotFoundException
from zodiac_core.logging import setup_loguru
from zodiac_core.middleware import register_middleware
from zodiac_core.routing import APIRouter

setup_loguru(level="INFO", json_format=True)
app = FastAPI()
register_middleware(app)
register_exception_handlers(app)

router = APIRouter()


@router.get("/items/{item_id}")
async def read_item(item_id: int):
    logger.info(f"request: item_id={item_id}")
    if item_id == 0:
        raise NotFoundException(message="Item not found")
    return {"item_id": item_id}


app.include_router(router)

🛠️ Developer & quality loop

Building on that core is also made safer for people and coding agents. Services get a quality loop: look up the version-matched docs before writing, audit adoption with a skill that runs zodiac check, and honor the project rules in AGENTS.md.

📚 Documentation

• Online: https://ttwshell.github.io/ZodiacCore-Py/ (multiple versions via release).
• Local: make docs-serve (sources in docs/).
• Developer skills: reusable agent skills ship in the zodiac-core wheel under zodiac/skills/. Link them with uv run zodiac skills install. Use zodiac-docs for version-aware framework guidance (including looking up docs before writing APIs) and zodiac-core-integration-summary for adoption audits (zodiac check --format json supplies mechanical wiring evidence). See the skills guide.

🤝 Contributing

Contributions are welcome. Please read CONTRIBUTING.md for development setup and workflow.

📄 License

This project is licensed under the MIT License.