Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.14.2] - 2026-08-28

Changed

  • Skills: zodiac-docs now auto-activates for version-matched docs, source, and tests when adding or changing ZodiacCore-backed APIs, and when the user asks how to use, migrate, troubleshoot, or verify ZodiacCore behavior. It requires resolving the target version and reading the matching source-map rows before editing code, so agents implement from version-matched documentation instead of memory.
  • Docs: README, the skills guide, and skill authoring notes now describe zodiac-docs as a look-up-before-writing-API preflight, and its agents/openai.yaml UI copy matches that scope.

[0.14.1] - 2026-08-25

Added

  • CLI: Add zodiac skills install and zodiac skills uninstall to link the packaged developer skills into a service project. Defaults to Codex (.agents/skills); --agent selects Claude, Cursor, Copilot, Gemini, or all. Unix creates a directory symlink; Windows creates a directory junction. Packaged zodiac-* skills are gitignored. zodiac new prints uv run zodiac skills install after uv sync --extra dev and does not auto-install.
  • Packaging: Ship zodiac-docs and zodiac-core-integration-summary in the zodiac-core wheel so installed skills follow the project's locked version instead of a copied tree.

Changed

  • Templates: Document uv run zodiac skills install (Codex by default; pass --agent for other clients) in generated AGENTS.md and README.md.
  • Documentation: Document skill install, uninstall, agent directories, and the uv sync then uv run flow in the CLI, getting-started, and skills guides.

Fixed

  • CLI: Walk up to pyproject.toml so install/uninstall run from a subdirectory still target the service root. Retarget stale packaged-skill links without --force; use --force only for copied directories. Preflight copied destinations before install so a conflict cannot leave a partial un-gitignored link. Match gitignore patterns on exact lines.

[0.14.0] - 2026-08-24

Added

  • CLI: Add zodiac check to AST-scan services that depend on zodiac-core for high-confidence wiring anti-patterns (FastAPI APIRouter, HTTPException, partial(get_session), bare session_dependency, raw httpx, layer imports, and bootstrap). Findings are grouped by rule with contract / change / docs printed once; --format json exposes per-rule counts for tools. Identity is a zodiac-core dependency; 3-tier, sub-application, and generic layouts are classified afterwards. Unused FastAPI APIRouter imports are warnings; constructing FastAPI's router is an error. Public zodiac_core re-exports of setup_loguru and register_* count as the same bootstrap calls as submodule imports.
  • Skills: zodiac-core-integration-summary runs uv run zodiac check --format json for mechanical wiring evidence and applies each error rule's change when the user asks to fix those cells. If the installed zodiac-core lacks zodiac check, prompt the user to upgrade and add zodiac-core[zodiac] to dev dependencies instead of running the latest CLI from uvx against an older lock.
  • Templates: Generate AGENTS.md for standard-3tier projects. Both templates point at uv run zodiac check as the wiring contract and keep the judgment rules the CLI cannot enforce (thin routers, DI, session ownership, request-derived database names, named resource lifecycle).

Changed

  • Templates: Include zodiac-core[zodiac] in the standard-3tier development extra so generated projects can run uv run zodiac check.
  • CLI: Print uv run zodiac check in zodiac new next steps.
  • Documentation: Document zodiac check in the CLI and getting-started guides. Route adoption audits and wiring-fix loops through zodiac-core-integration-summary. A green report certifies mechanical wiring, including import-layer anti-patterns, not architecture.

[0.13.0] - 2026-08-07

Added

  • Database: Add session_dependency(name) for FastAPI dependencies that are bound to a named database without exposing the database name as a request parameter.
  • Routing: Support FastAPI-native synchronous and asynchronous yield streaming, including JSONL, binary streams, SSE, callable objects, and wrapped generator endpoints when supported by the installed FastAPI version.

Changed

  • Routing: Infer omitted response models from endpoint return annotations, preserve an untyped Zodiac envelope for unannotated payloads, and leave raw responses and bodyless status codes outside the envelope.
  • Cache: Require serializers used with cached None values to restore None losslessly and reject incompatible serializers during decorator setup.
  • Documentation: Define database-session ownership for dependencies, repositories, services, jobs, and mounted sub-applications, and clarify the existing upstream HTTP error translation contract.

Fixed

  • Database: Prevent request input and unsafe partial dependencies from overriding server-selected database names while preserving dependency overrides, caching, cleanup, and introspection.
  • Cache: Preserve cached None values across JSON and other compatible serializer boundaries without leaking the internal sentinel.
  • Validation: Encode validation errors with FastAPI's native jsonable_encoder behavior before placing them in Zodiac's HTTP 422 envelope.
  • Routing: Avoid invalid response models and runtime wrapping for raw, Annotated, bodyless, and streaming endpoints across supported FastAPI versions.
  • Datetimes: Preserve PostgreSQL timestamptz defaults in non-UTC sessions and normalize parsed datetime strings to aware UTC values.

[0.12.0] - 2026-07-23

Added

  • Cache: Add a keyword-only lease option to @cached for overriding the default two-second RedLock lease.
  • Codex Skills: Add the repository-hosted zodiac-docs skill for version-aware framework guidance based on matching documentation, source code, tests, and generated templates.

Changed

  • Standard Template: Load logging level, JSON format, and service name from application configuration.
  • Generated Tests: Add an isolated testing profile with pytest-env, in-memory SQLite, a test-specific cache prefix, and reduced log output.
  • Sub-applications: Decouple application services from API schemas by passing validated resource fields from routers.
  • Generated Projects: Use --no-access-log in Uvicorn commands to prevent duplicate request logs from Uvicorn and ZodiacCore middleware.
  • Codex Skills: Document project-level skill installation under .agents/skills/.

Fixed

  • Logging: Preserve supplied exception tracebacks in text and JSON logs, including structured exception metadata and record.extra.exception_traceback.
  • Templates: Use receiver-aware cache keys for generated GitHubService instance methods so equivalent dependency-injection instances share cached results correctly.

[0.11.1] - 2026-07-14

Added

  • CLI: Add zodiac add sub-app NAME to generate a mountable service and contract tests inside an existing sub-applications project, with configurable resources, automatic regular and irregular pluralization, explicit plural overrides, package detection, and printed wiring instructions.
  • Templates: Add a reusable parameterized sub-application scaffold with ZodiacCore routing, schemas, dependency injection, SQLModel persistence, pagination, filtering, sorting, and API contract tests.
  • Codex Skills: Add the repository-hosted zodiac-core-integration-summary skill and installation guidance for auditing ZodiacCore adoption in downstream services.

Changed

  • Sub-applications: Generate the built-in users and orders examples from the reusable scaffold and standardize them on a minimal name-based CRUD contract.
  • Generated Projects: Include zodiac-core[zodiac] in the development extra and reset shared database state around generated-project tests.

Removed

  • Templates: Remove the generated users and orders service metadata endpoints and their cache demonstration code from new sub-application projects.

Fixed

  • Scaffolding Safety: Reject unsafe project names and destinations that escape the requested output root through absolute paths, traversal, or symbolic links, preventing --force from overwriting files outside the project.
  • Template Rendering: Validate template context strictly, preflight destination conflicts, and restore overwritten or newly created paths after write failures to avoid partial scaffolds.

[0.11.0] - 2026-07-07

Added

  • Templates: Add a sub-applications scaffold for a parent FastAPI server with mounted users and orders services, shared parent-owned database/cache lifecycle, scoped middleware/logging, exception handlers, and generated contract tests.
  • CLI: Support zodiac new PROJECT_NAME --tpl sub-applications -o OUTPUT_DIR for generating multi-app service projects.
  • Docs: Add a sub-applications guide for FastAPI mounts, sub-app lifespan handling, process-global logging, shared or named database/cache resources, and shutdown ownership.
  • Templates: Include keyword filtering, whitelisted sorting, ZodiacCore schema bases, in-memory testing configuration, and Codex project guidance in the generated sub-applications project.

Changed

  • Repositories: Return clearer unsupported-sort errors with the rejected field and supported sort fields in response metadata.

[0.10.0] - 2026-07-02

Added

  • Pagination: Add reusable multi-column sorting query models (SortParams, PageSortParams) and SortSpec for explicit repository sort whitelists and default ordering.
  • Repositories: Add validated sorting support to BaseSQLRepository.paginate(), paginate_query(), and apply_sorting().
  • Middleware: Add exclude_paths support to skip noisy HTTP access logs such as health checks.

Changed

  • Pagination: Use repeated query parameters such as ?sort=created_at:desc&sort=name:asc for multi-column sorting.
  • Repositories: Use SortSpec as the only repository sorting configuration API.
  • Templates: Update generated repository, service, router, and middleware setup code to use PageSortParams, repository-level SortSpec, and health-check access-log exclusion.
  • Docs: Document multi-column sorting, SortSpec, repository sorting helpers, service-name middleware, and access-log path exclusions.

[0.9.1] - 2026-06-02

Added

  • HTTP: Log translated upstream HTTP errors with structured context, including service, error type, request method, upstream URL, status code, and capped upstream response body details.
  • Exceptions: Include upstream status and response body details in UpstreamRequestException responses for upstream HTTP 400/422 failures.

Fixed

  • HTTP: Handle httpx.RequestError instances without request metadata without raising a secondary exception during upstream error translation.
  • Exception Handlers: Log inbound request context when returning standardized upstream error responses.
  • Docs: Document upstream error logging fields and 400/422 response details.

[0.9.0] - 2026-04-29

Added

  • HTTP: Add translate_upstream_errors(service) to convert httpx upstream status and request failures into standardized ZodiacCore exceptions for both async and sync functions.
  • Exceptions: Add UpstreamServiceException and UpstreamRequestException for explicit upstream service failures, including service name and upstream error classification.
  • Exception Handlers: Register a dedicated upstream exception handler that returns standardized HTTP 400 responses for translated upstream failures.
  • Templates: Update the standard-3tier external client example to use ZodiacClient with translate_upstream_errors.
  • Docs: Document upstream error translation, manual upstream business-error mapping, and the new upstream exception types in the exceptions API guide.
  • Tests: Add coverage for upstream exception behavior, handler registration, async/sync HTTP translation, and template usage.

[0.8.1] - 2026-04-26

Fixed

  • Exceptions: Respect http_code declared on direct ZodiacException subclasses when converting them to HTTP responses, while preserving fixed HTTP statuses for built-in exception families.

Changed

  • Docs: Clarify the distinction between HTTP status codes and business error codes, including how built-in exception families and direct ZodiacException subclasses should be used.

[0.8.0] - 2026-04-14

Added

  • CLI: --package-name option for zodiac new command to customize the generated Python package name (defaults to app).
  • Middleware: ServiceNameMiddleware for scoping service names in request context, allowing per-app log attribution in multi-app deployments.
  • Context: service_name_scope and get_service_name for managing service-level context in zodiac_core.context.
  • Logging: Loguru patcher now prefers service_name from context if available, enabling accurate service tagging in shared logging sinks.
  • Templates: standard-3tier template now fully supports dynamic package names and includes ServiceNameMiddleware registration by default.
  • Tests: Comprehensive multi-app integration tests (tests/multi_app/dual_full_apps/) using real Uvicorn servers to validate isolation and shared resources.

Changed

  • CLI: zodiac new now validates package names against Python identifiers and reserved names (main, config, tests).
  • Middleware: register_middleware now accepts an optional service_name to automatically enable ServiceNameMiddleware.
  • Docs: Documentation updated with --package-name usage and architectural details for multi-app setups.

[0.7.0] - 2026-03-31

Added

  • Database: get_session() accepts an optional name parameter for multi-database support; defaults to the default database for backward compatibility.
  • Config: StrictConfig base model (extra='forbid', frozen=True) for configuration section Pydantic models — rejects typo keys and prevents mutation after creation.
  • Utils: strtobool() as a Python 3.13+ compatible drop-in replacement for the removed distutils.util.strtobool, returning bool instead of int.
  • Docs: Best practices guide for dependency-injector Configuration (strict mode, required files, type conversion pitfalls, environment variable interpolation).
  • Docs: API reference page for the zodiac_core.utils module.
  • Tests: Integration tests for dependency-injector strict=True + required=True + as_(strtobool) and StrictConfig constraints; dependency-injector added as dev dependency.

Changed

  • Template: Generated projects use providers.Configuration(strict=True) and from_ini(path, required=True) for fail-fast configuration loading.
  • Template: Config models (DbConfig, CacheConfig) inherit StrictConfig instead of BaseModel; type conversion uses Pydantic models via ConfigManagement.provide_config() instead of manual as_() calls.
  • Docs: All code examples across config, context, architecture, and getting-started guides updated to use strict=True, required=True, and strtobool imports from zodiac_core.utils.

Fixed

  • Config: Replace as_(bool) / as_=bool with as_(strtobool) for boolean config values — bool("false") evaluates to True, causing silent misconfiguration.
  • Tests: Force reinstall zodiac-core in generated project quality test to prevent stale uv cache from masking template breakage.

[0.6.1] - 2026-03-27

Added

  • Cache: Optional include_cls and include_self on @cached so the default key builder can fold receiver class identity into the key for classmethods (cls) and instance methods (self), gated by conventional first-parameter names; document that include_self is class-scoped (not per-instance) and that inheritance changes cache partitioning when enabled.
  • Tests: Expand @cached coverage for custom key_builder, include_cls with base/derived classes, include_self sharing across instances of the same class, parent/child class separation, and instance methods that still require an explicit key_builder when receiver-aware keys are omitted.

Changed

  • Docs: Add a “Receiver-aware default keys” section to the cache API guide (constraints, warnings, and examples for class vs instance methods).

[0.6.0] - 2026-03-26

Added

  • HTTP: Add init_http_client() as a lifecycle helper for creating and closing a shared ZodiacClient within an application or DI resource.
  • Database: Add scoped shutdown support via db.shutdown(name="...") so a single named database can be released without disposing all registered engines.
  • Cache: Add scoped shutdown support via cache.shutdown(name="...") so a single named cache can be released without clearing all registered caches.
  • Tests: Add coverage for named database/cache shutdown and for init_db_resource() cleaning up only its own database name.

Changed

  • Database: Make DatabaseManager.setup() deterministic by allowing repeated setup only for the same effective configuration and raising RuntimeError for conflicting configuration on an existing name.
  • Database: Make init_db_resource() release only the database registered under its own name, preserving other shared database resources in the same process.
  • Template: Manage the shared HTTP client as an application resource in the standard 3-tier template and initialize app resources through AsyncExitStack.
  • Template: Align generated project configuration loading with APPLICATION_ENVIRONMENT and default the template fallback environment to develop.
  • CLI: Clarify that zodiac new --force allows generation into an existing directory without removing unrelated files.
  • Docs: Update database, cache, config, context, architecture, CLI, and getting-started documentation to reflect the scoped resource lifecycle and template conventions.

Fixed

  • Template: Ensure generated projects use resource lifecycle management for shared HTTP clients instead of relying on unmanaged singleton client instances.

[0.5.4] - 2026-03-23

Changed

  • Cache: Restrict the default @cached key builder to stable immutable parameters and require an explicit key_builder for complex arguments instead of falling back to unstable automatic keys.
  • Cache: Make cache.setup(...) deterministic by allowing repeated setup only for identical effective configuration and raising RuntimeError for conflicting settings.
  • Docs: Clarify cache setup idempotency rules and document the supported/default key-builder constraints for @cached.

Fixed

  • Cache: Decode the internal cached-None sentinel in public get() while preserving correct get_or_set() hit detection under lock rechecks.
  • Cache: Preserve default_ttl when rebuilding a ZodiacCache wrapper from an existing aiocache alias.

Added

  • Tests: Expand cache coverage for tuple-based default keys, deterministic setup behavior, wrapper rebuild state, public get() after cached None, and the cached-None lock recheck path.

[0.5.3] - 2026-03-17

Fixed

  • Logging: When json_format=True, use empty "text" in serialized JSON so the message appears only in record.message, avoiding duplication and reducing log size (loguru#594).

Changed

  • Logging: Unify console and file sink defaults in setup_loguru() via shared _sink_defaults and _apply_sink_defaults(); document empty-text behavior and override via console_options/file_options in docstring.

[0.5.2] - 2026-03-09

Fixed

  • HTTP: Use HTTP_422_UNPROCESSABLE_CONTENT (RFC 9110) instead of deprecated HTTP_422_UNPROCESSABLE_ENTITY in UnprocessableEntityException and response_unprocessable_entity(), resolving Starlette deprecation warnings.

Changed

  • Dependencies: Require starlette>=0.48.0 so the RFC 9110 status constant is available.

[0.5.1] - 2026-03-06

Added

  • Cache: Support for synchronous functions in the @cached decorator. The decorated function becomes asynchronous and must be awaited by the caller, allowing cache reuse for both async and sync business logic.
  • Template: Integrated cache support into the standard-3tier project template, including optional dependency, configuration, initialization in main.py, and README usage notes.
  • Tests: Test cases for sync function support in the @cached decorator.

Changed

  • Docs: Cache API docs clarify that @cached supports both async and sync functions; add usage examples and note that caller must always await.

[0.5.0] - 2026-03-04

Added

  • Cache: Unified cache layer on aiocache (optional extra zodiac-core[cache]). CacheManager singleton with setup(prefix, ...) / get_cache(name) / shutdown(); ZodiacCache with get / set / delete / exists and get_or_set (RedLock stampede protection, optional skip_cache_func). @cached(ttl, key_builder, name, skip_cache_func) decorator for async functions; default key builder hashes fn + args (pickle with repr fallback for unpicklable args). Namespace zodiac_cache:{prefix}; multi-cache via name parameter.
  • Docs: Cache API documentation (docs/api/cache.md) for setup, decorator, get_or_set, and named caches.
  • Tests: Cache test suite (decorator key/name/skip_cache_func, manager setup/get_cache/shutdown, ZodiacCache get_or_set/RedLock/skip_cache_func); integration test for optional [cache] extra.

[0.4.0] - 2026-03-03

Added

  • Middleware: WebSocket support for TraceIDMiddleware and AccessLogMiddleware. Request ID is read from the WebSocket upgrade request headers (or generated), set in context for the connection lifetime, and reset on close. Access log records WEBSOCKET {path} - 101 - {latency}ms. Lifespan scope is passed through without request_id or access log.
  • Context: request_id_scope(request_id) context manager to set and reset request ID on exit (used internally by middleware; available for custom ASGI apps that need the same semantics).

Changed

  • Middleware: Replace BaseHTTPMiddleware with Pure ASGI implementation for TraceIDMiddleware and AccessLogMiddleware. Request handling uses scope / receive / send directly, improving latency and stability under load. Module docstring links to ASGI spec for scope types (http, websocket, lifespan).
  • Makefile: make bench-compare supports an optional run ID (e.g. make bench-compare ID=0002); default remains 0001.
  • Docs: Clarify uv usage and scaffold flow in installation and getting-started; reduce redundancy in CLI and scaffold docs.
  • Template: Use async httpx client in standard-3tier generated tests.

Other

  • Tests: Add middleware tests for WebSocket and lifespan behavior; add coverage for response helpers, HTTP client hooks, and schemas ensure_utc.

[0.3.0] - 2026-02-25

Added

  • Exceptions: UnprocessableEntityException (HTTP 422) for business/semantic validation errors when the request is well-formed but not processable. Exception definitions, handlers, exports, and docs are ordered by HTTP status code (400–422).
  • CI & coverage: Upload coverage reports to Codecov in CI and enable XML coverage reports (--cov-report=xml) for tooling integration.
  • Database tests: Add an async integration test for DatabaseManager.verify() to ensure database connectivity can be checked reliably.

Changed

  • README: Replace badge layout with concise shields, adding direct links to documentation, PyPI, and Codecov status.
  • Tooling: Update ignore rules to keep generated coverage artifacts (coverage.xml) out of version control, while keeping docs changelog managed through the docs site.

[0.2.1] - 2026-02-11

Fixed

  • Dependency Isolation: Fixed an issue where zodiac_core.db submodules forced sqlalchemy imports. Now optionally loads and provides clear installation guidance when zodiac-core[sql] is missing.

[0.2.0] - 2026-02-06

Added

  • zodiac CLI: zodiac new PROJECT_NAME --tpl standard-3tier -o OUTPUT_DIR to scaffold projects (optional extra zodiac-core[zodiac]).
  • standard-3tier template: Full FastAPI project with 3-tier architecture (API / Application / Infrastructure), dependency-injector, file-based config (.ini), and Container.initialize() that auto-wires all *_router modules.
  • Config: ConfigManagement.provide_config(config, model) — optional Pydantic model for type-safe, validated config (backward compatible with SimpleNamespace).
  • Database: BaseSQLRepository.paginate() and paginate_query() for standardized pagination with count and optional schema transformation.
  • Documentation: Architecture guide (layered design, DI, wiring), CLI guide, pagination API (repository methods), and getting-started aligned with template.

[0.1.0] - 2026-02-02

Added

  • Routing: ZodiacAPIRouter with automatic Response[T] wrapping using Pydantic v2 native generics
  • Response: Standard API response model Response[T] with code, data, message fields
  • Exceptions: ZodiacException hierarchy (NotFoundException, BadRequestException, ForbiddenException, UnauthorizedException, ConflictException)
  • Exception Handlers: Centralized handlers for ZodiacException, RequestValidationError, and generic exceptions
  • Middleware: TraceIDMiddleware for request tracing, AccessLogMiddleware for structured access logging
  • Logging: setup_loguru() with JSON format support and Trace ID injection
  • Context: trace_id context variable for cross-cutting request tracing
  • Config: BaseAppSettings with environment-based configuration using Pydantic Settings
  • Database:
  • DatabaseManager singleton for async SQLAlchemy engine/session management
  • BaseSQLRepository with session context manager
  • SQLModel mixins: IntIDMixin, UUIDMixin, SQLDateTimeMixin
  • HTTP: HttpClient async wrapper around httpx with automatic Trace ID propagation
  • Pagination: PageParams request model and PagedResponse[T] response model
  • Schemas: Pydantic mixins: IntIDSchemaMixin, UUIDSchemaMixin, DateTimeSchemaMixin
  • Benchmarks: Performance benchmarks for routing overhead and internal operations
  • Documentation: MkDocs-based API reference and user guide