From 715bfd8022c75b0543a55957335a22f3a749b833 Mon Sep 17 00:00:00 2001 From: Vishesh 'ironeagle' Bangotra Date: Mon, 12 Oct 2026 21:20:38 +0530 Subject: [PATCH] docs(standards): document internal-library bootstrap; wire private index into template Dockerfile --- standards/src/templates/README.md | 62 ++++++++++++++++++++++---- standards/src/templates/app/Dockerfile | 7 ++- 2 files changed, 59 insertions(+), 10 deletions(-) diff --git a/standards/src/templates/README.md b/standards/src/templates/README.md index 1a7ea62..552c375 100644 --- a/standards/src/templates/README.md +++ b/standards/src/templates/README.md @@ -6,11 +6,32 @@ both axes of the blueprint (see `standards`): 1. **Resource axis** — items and jobs, each a Claude-style generic CRUD slice (model → document → repo → service → route), all driven from `openapi.yaml`. 2. **Pipeline axis** — a background `worker.py` that polls pending jobs and runs - `pipelines/item_sync.py`, a deterministic async step chain. + a pipeline; `pipelines/example/` shows the reusable family skeleton and + `pipelines/item_sync.py` the simple end-to-end form. Everything here is deliberately small so an agent can rewrite each file rather than delete unused code. The domain is a neutral "item", not an app noun. +## Internal dependencies + +The app depends on the internal Aetos libraries (`openapi-first`, `mongo-ops`, +`hexa`, `dagpipe`, `doc-forge`). Install them one of two ways. + +- **Local checkouts (preferred in development)** — install the sibling repos + editable: + + pip install -e ../aetos/openapi-first -e ../aetos/mongo-ops -e ../aetos/hexa ` + -e ../aetos/dagpipe -e ../aetos/doc-forge + +- **Private index (CI / fresh machines)** — the published wheels live on the + Aetos index. Pass credentials through the environment only; never commit them: + + pip install --extra-index-url ` + "https://$PIP_REGISTRY_USERNAME:$PIP_REGISTRY_PASSWORD@pip.aetoskia.com/simple" . + + The `Dockerfile` reads `PIP_REGISTRY_USERNAME` / `PIP_REGISTRY_PASSWORD` as + build args and sets `PIP_EXTRA_INDEX_URL` accordingly. + ## Instantiate a new app cp -r src/templates/app apps/ @@ -20,17 +41,34 @@ than delete unused code. The domain is a neutral "item", not an app noun. 2. `config.py` — replace/add settings consumed by your domain. 3. `openapi.yaml` — replace the `Item`/`Job` resources with your resources. 4. `domain/` — rename `item` and `job` slices to your aggregates. -5. `pipelines/item_sync.py` — replace the demo steps with your pipeline. +5. `pipelines/` — replace the demo with your pipeline (see below). 6. `tests/` — keep the two test files as the pattern for your own. -Run the API: +Install and run: pip install -e ".[dev]" - uvicorn main:app --reload + uvicorn main:app --reload # API + python worker.py # worker + python -m scripts.seed # operator script -Run the worker: +## Pipeline families - python worker.py +`pipelines/item_sync.py` is the smallest possible pipeline (plain async steps). +When a family needs its own stages, copy `pipelines/example/`: + + pipelines// + abc.py # port contracts + impl.py # concrete stages + wired root + register(...) + pipeline.yaml # graph spec + resources/ + pipeline.yaml # runtime spec + patterns/*.yaml + pipelines/shared/ + ports.py loader.py registry.py # reused by every family + +The shared loader wires the root through the DI library (`hexa.build`) and merges +the pattern fragments; the registry resolves a `(kind, variant, mode)` triple to +a root class. See standards "06_pipeline_scaffold". ## What to keep, what to replace @@ -41,14 +79,20 @@ Run the worker: | openapi-first routing | Paths, schemas, operationIds | | mongo-ops repo factory | Collections, doc models | | generic CRUD adaptor | Nothing (reuse as-is) | +| `pipelines/shared/` | Nothing (reuse as-is) | +| `pipelines/example/` | Family name, stages, patterns | | worker poll + status loop | Job payloads, pipeline steps | +| `scripts/` | Task bodies | ## Where the internal libraries slot in - `openapi_first.app.OpenAPIFirstApp` — main.py, interfaces/openapi.py - `mongo_ops` — infra/db/setup.py, infra/db/repos/mongo.py, domain/*/ports/db.py -- `hexa.build` — domain/*/ports/service.py +- `hexa.build` — domain/*/ports/service.py, pipelines/shared/loader.py - `dagpipe` — pipelines/ (wrap step chains in a DAG once they branch) +- `docforge` — generated `.pyi` stubs and docs +- `omniread` / `mail-intake` — ingestion adapters (add when needed) -Confirm current endpoints and ownership with the `standards` registry MCP tool: -`find_library("pipeline")`, `find_library("auth")`, etc. \ No newline at end of file +Confirm current endpoints and ownership with the `standards` registry MCP tools: +`find_library("pipeline")`, `find_library("auth")`, or +`get_app_component("pipeline-abc", family="csv")`. diff --git a/standards/src/templates/app/Dockerfile b/standards/src/templates/app/Dockerfile index 19cd195..b39d077 100644 --- a/standards/src/templates/app/Dockerfile +++ b/standards/src/templates/app/Dockerfile @@ -2,10 +2,15 @@ FROM python:3.11-slim WORKDIR /app +# Private index for the internal Aetos libraries — pass credentials as build args. +ARG PIP_REGISTRY_USERNAME +ARG PIP_REGISTRY_PASSWORD +ENV PIP_EXTRA_INDEX_URL=https://${PIP_REGISTRY_USERNAME}:${PIP_REGISTRY_PASSWORD}@pip.aetoskia.com/simple + COPY pyproject.toml ./ COPY . . RUN pip install --no-cache-dir --upgrade pip \ - && pip install --no-cache-dir . + && pip install --no-cache-dir --extra-index-url "${PIP_EXTRA_INDEX_URL}" . EXPOSE 8000