Metadata-Version: 2.4
Name: ai-project-blueprints
Version: 0.3.0
Summary: Validated, versioned project blueprint catalog for coding agents
Requires-Python: >=3.14
Description-Content-Type: text/markdown
Requires-Dist: jsonschema<5,>=4.25
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: pyright<2,>=1.1.405; extra == "dev"
Requires-Dist: pytest<10,>=8.4; extra == "dev"
Requires-Dist: pytest-xdist<4,>=3.8; extra == "dev"
Requires-Dist: ruff<1,>=0.13; extra == "dev"
Requires-Dist: twine<7,>=6.2; extra == "dev"

# AI Project Blueprints

Versioned, inspectable starter packs for agents that create new projects. A pack
combines a machine-readable manifest, agent instructions, dependency policies,
and template assets. It is deliberately separate from the orchestrator: the
orchestrator resolves and previews a pack, while this repository owns its content.

The latest backend pack is `python-api-fastapi@1.2.0`; immutable `1.0.0` and `1.1.0`
remain available. Its base profile uses FastAPI,
Pydantic Settings, SQLAlchemy 2, Alembic, Ruff, Pyright, pytest and pytest-xdist.
Exactly one database profile is selected: PostgreSQL by default or SQLite for
bounded embedded/single-instance use. Testcontainers/PostgreSQL,
Keycloak-compatible OIDC, Docker, and Kubernetes/Helm are explicit overlays.
Version `1.1.0` adds feature-first vertical slices and lets agents choose the
least elaborate internal structure for each use case.
Version `1.2.0` limits pack instructions to the FastAPI layout, selected stack,
overlays and concrete checks. Its application templates are unchanged. Existing
service profiles stay pinned to `1.1.0`; select `1.2.0` directly through its
manifest when adopting the separated instruction layout.

The UI pack `react-spa-vite@1.0.0` provides a browser-only React and strict
TypeScript SPA with Vite, React Router, typed ESLint, Prettier, Vitest, and React
Testing Library. Its feature-first structure keeps page-local journeys small and
promotes reusable interactions or shared domain representations only when their
boundaries are proven. Tailwind, OpenAPI client generation, TanStack Query,
React Hook Form with Zod, OIDC/Keycloak, MSW, Playwright, runtime configuration,
and non-root nginx delivery are explicit capabilities. The
`react-admin-api-spa` service profile selects that recommended administrative UI
combination without changing the minimal blueprint defaults.

The standalone `python-toolkit@2.0.0` pack provides a Python 3.14+ library, JSON
CLI and packaged instructions/resources. It starts with a standard-library runtime,
Ruff, strict Pyright, pytest, coverage, xdist, build and twine. A consumer-owned uv
lock makes development reproducible. It includes portable Python verification
scripts and an installed-wheel smoke outside the source tree. A single agent can
use it directly, without service/platform profiles. See the
[Python toolkit policy](src/ai_project_blueprints/resources/docs/python-toolkit-policy.md).

The instruction-only set
[`dotnet-project-guidance@2.5.0`](src/ai_project_blueprints/resources/instruction-sets/dotnet-project-guidance/2.5.0/agent.md)
provides portable C# vertical slices, compact compiler/analyzer-checked style,
isolated parallel tests and document-owned test references and shared optional runner adapters. It can
be adopted by existing services, workers, CLIs, libraries and fixture drivers.
Version2.1.0 adds SDK build checks, CleanupCode formatting and local InspectCode
after cohesive functionality blocks and at final task review before commit.
Version2.5.0 adds one canonical documentation tree with module ownership, separate
current procedures and dated evidence, and explicit migration checks. It is a
portable convention for new applications; existing projects keep their layout
until a scoped migration. Version2.4.0 moves test references into owner documents and uses shared evidence
adapters with semantic closure review. It retains standard SDK/JetBrains checks and review gaps
when retiring custom analyzers. Earlier versions remain immutable.
Version2.2.0 adds explicit module contracts, matching functional test projects
and bounded change context. Contract-first coordination supports repository-owned
modules and internal functional blocks when the consumer workflow permits
delegation; this guidance does not change the orchestrator's execution policy.
Versions1.0.0,2.0.0 and2.1.0 remain available unchanged.
It supplies guidance, without declaring an executable .NET starter or service
profile. Existing projects explicitly record the exact adopted version and
resource hashes; package updates do not rewrite their instructions.

Project-level operations are modeled separately through immutable platform
packs. `local-compose@1.0.0` provides a development dependency boundary;
`kubernetes-standard@1.0.0` provides provider-neutral Helm, Argo CD, Gateway
API, OIDC, OpenTelemetry with an explicit telemetry backend, secret-management,
backup, scheduler and event decisions. Stateful additions such as Keycloak,
Velero, a self-hosted observability stack or a message broker stay explicit
capabilities rather than silent service defaults.

## Installation and API

```bash
pip install ai-project-blueprints==0.3.0
ai-project-blueprints list
ai-project-blueprints platform-list
ai-project-blueprints validate
```

Distribution 0.3.0 includes the toolkit packs, Python guidance and .NET instruction sets.
[Release notes and migration](src/ai_project_blueprints/resources/docs/release-0.3.0.md)
explain the Python 3.14 requirement and explicit resource adoption. Inspect the
installed resources through the public CLI:

```bash
ai-project-blueprints manifest python-toolkit 2.0.0
ai-project-blueprints blueprint-smoke python-toolkit 2.0.0
ai-project-blueprints read catalog/instruction-sets.json
ai-project-blueprints read instruction-sets/dotnet-project-guidance/2.5.0/agent.md
```

Python consumers use `ai_project_blueprints` to discover and read resources.
Access is backed by `importlib.resources`, so an installed wheel does not depend
on a repository checkout:

```python
from ai_project_blueprints import load_manifest, load_platform_manifest, read_text

manifest = load_manifest("python-api-fastapi", "1.2.0")
coder_instructions = read_text("blueprints/python-api-fastapi/1.2.0/instructions/coder.md")
platform = load_platform_manifest("kubernetes-standard", "1.0.0")
```

For instruction-only sets, use `load_catalog("instruction-sets")`, then
`read_json(entry["manifest"])` and `read_text()` for each declared instruction
relative to that manifest's directory. `resource_inventory("instruction-sets")`
lists their packaged files. The same reads work from an installed wheel.

The API and CLI are inspect-only. They do not materialize or overwrite project
files.

## Python project guidance

[`python-project-guidance@1.0.0`](src/ai_project_blueprints/resources/instruction-sets/python-project-guidance/1.0.0/agent.md)
owns general Python architecture, types, dependencies, persistence, diagnostics
and verification. Its conditional worker guidance covers bounded I/O concurrency,
task/process ownership, cancellation, durable acceptance, retries and recovery.
The manifest declares all four instruction documents. The set selects no
framework, database, broker or service profile and creates no worker starter.

Adopt the set independently of a blueprint. To use it alongside FastAPI `1.2.0`,
record both exact manifests, load the set's declared instructions, then apply the
pack's stack-specific instructions. Neither selection implicitly loads the other.
These resources are included in distribution 0.3.0 and can be read through the
installed public API:

```python
from ai_project_blueprints import read_json, read_text

prefix = "instruction-sets/python-project-guidance/1.0.0"
manifest = read_json(f"{prefix}/manifest.json")
entrypoint = read_text(f"{prefix}/agent.md")
engineering = read_text(f"{prefix}/engineering.md")
worker = read_text(f"{prefix}/worker.md")
```

Use `ai-project-blueprints read instruction-sets/python-project-guidance/1.0.0/agent.md`
for JSON CLI output. Record the distribution version, set ID/version and complete
resource hashes. Existing `docs/python-engineering-policy.md` and
`docs/python-worker-policy.md` paths remain navigation pages; existing local copies
retain their provenance until explicitly migrated. See the
[package contract](src/ai_project_blueprints/resources/docs/package-contract.md#supplemental-engineering-instructions)
and [ownership and verification plan](docs/plans/python-guidance.md).

## Compatibility inspection

Совместимость можно проверить через `compatibility_matrix()`,
`resolve_combination()` и `golden_smoke()` либо команды
`compatibility-matrix` и `compatibility-smoke`. Матрица schema version 1
детерминированно выводится из canonical service/platform catalog и manifest,
поэтому неизвестный profile или capability отклоняется. Golden smoke собирает
объявленные файлы только в памяти, подставляет manifest examples/defaults,
сводит выбранные npm dependency records и прекращает работу при missing source
или target collision; consumer-файлы он не создаёт и не перезаписывает.

## Layout

```text
src/ai_project_blueprints/resources/  packaged catalogs, schemas, docs, examples, and packs
src/ai_project_blueprints/            public API, CLI, and trusted validation tooling
tests/         catalog invariant tests
```

## Validate

Python 3.14+ is required for the catalog tooling. CI quality checks, builds and
publication use Python 3.14. Recreate older environments before upgrading to a
new package release with this minimum.

```bash
python -m venv .venv
.venv/bin/pip install -e '.[dev]'
.venv/bin/ai-project-blueprints validate
.venv/bin/ruff check .
.venv/bin/pyright --pythonpath .venv/bin/python
.venv/bin/pytest -n auto
```

The current release is a catalog contract and authored template pack. It does not
yet include a materializer; consumers must preview an exact manifest version and
preserve caller-owned files when they implement materialization.

Обычная проверка использует bounded `core` tier. Команды, которым действительно
нужны Docker, Helm, browser E2E или capability `testcontainers-postgresql`,
попадают в отдельный `heavyweight` tier и появляются только при выборе
соответствующей capability.
Opt-in CI с `BLUEPRINT_GENERATED_SMOKE=1` дополнительно материализует проекты во
временный каталог и запускает install, lint, typecheck, tests, build и SQLite
migration smoke. Временный каталог удаляется после проверки.

Standalone toolkit smoke resolves a fresh consumer lock and runs the generated
sequential/parallel gates, build and runtime-only installation:

```bash
python scripts/generated_toolkit_smoke.py --execute --python 3.14 --uv /path/to/uv
```

The same opt-in CI flag runs the catalog driver on Python 3.14 and checks the
generated 1.0.0 project on Python 3.11/3.14 and 2.0.0 on Python 3.14. These are
the immutable packs' consumer runtimes, selected with `--python` independently
of the catalog environment. The React smoke retains Node 24 and bootstraps a
Python 3.14 driver with pinned uv. Without `--execute`, the script only renders
into temporary storage and needs no uv or network. `blueprint_smoke()` provides
the in-memory variant through the package API.

## Multi-service orchestration

[`catalog/service-workflows.json`](src/ai_project_blueprints/resources/catalog/service-workflows.json) separates
three provider-neutral concepts: a `service_profile` chooses blueprint defaults,
an `agent_bundle` supplies ordered role instructions, and a `workflow_bundle`
describes one bounded service workflow. The consumer-owned
[`examples/python-multiservice-project.json`](src/ai_project_blueprints/resources/examples/python-multiservice-project.json)
shows backend services using different PostgreSQL/SQLite profiles and a React
administrative UI using its own profile, instruction bundle, workflow bundle,
and runtime-profile aliases under one workspace orchestrator.

[`catalog/platform-workflows.json`](src/ai_project_blueprints/resources/catalog/platform-workflows.json)
adds environment-level platform profiles, agent bundles and bounded platform
workflows. Workspace schema version 2 binds `local` to Compose and
`staging`/`production` to Kubernetes while retaining per-role runtime aliases.
Service workflows consume the resulting operational contracts but do not own
shared cluster resources.

Concrete runtime aliases, models, providers, credentials and service-local
instructions remain consumer-owned. The catalog only validates their safe
logical bindings. Cross-service work is serialized and composed by the single
host; a service workflow cannot start a nested orchestrator or independently
claim the same checkout.

See [the Python API stack policy](src/ai_project_blueprints/resources/docs/stack-policy.md)
and [the React SPA stack policy](src/ai_project_blueprints/resources/docs/ui-stack-policy.md)
and [the feature-first architecture policy](src/ai_project_blueprints/resources/docs/code-architecture-policy.md)
and [the platform profile policy](src/ai_project_blueprints/resources/docs/platform-policy.md)
for selection rationale. The [package contract](src/ai_project_blueprints/resources/docs/package-contract.md)
and [release policy](src/ai_project_blueprints/resources/docs/release-policy.md)
define resource compatibility and GitLab.com/PyPI publication gates.

.NET guidance2.0.0 adds one project per application, cohesive shared modules,
EF Core persistence/migration bundles and copyable project-layout templates.
Immutable1.0.0 remains available. These instruction/example changes are included in distribution0.3.0.
Instruction-set versions are independent of the distribution version.
