diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 52f1254..82379a2 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,6 +1,6 @@ --- name: Bug report -about: Report a defect in civiccore +about: Report a defect in townlight_core title: "[bug] " labels: ["bug"] --- @@ -19,7 +19,7 @@ labels: ["bug"] **Environment** -- civiccore version (`python -c "import civiccore; print(civiccore.__version__)"`): +- townlight_core version (`python -c "import townlight_core; print(townlight_core.__version__)"`): - Python version: - Consuming application (records-ai, custom, evaluation): - Postgres version (if migration-related): diff --git a/.github/ISSUE_TEMPLATE/documentation.md b/.github/ISSUE_TEMPLATE/documentation.md index 0c5206e..dc303ea 100644 --- a/.github/ISSUE_TEMPLATE/documentation.md +++ b/.github/ISSUE_TEMPLATE/documentation.md @@ -16,4 +16,4 @@ labels: ["documentation"] **Audience this affects** - [ ] Module developer / IT integrator - [ ] Consuming application (records-ai, future modules) -- [ ] Evaluator (deciding whether to use civiccore) +- [ ] Evaluator (deciding whether to use townlight_core) diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index d416e40..144a8ac 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,6 +1,6 @@ --- name: Feature request -about: Suggest an enhancement to civiccore +about: Suggest an enhancement to townlight_core title: "[feat] " labels: ["enhancement"] --- @@ -14,6 +14,6 @@ labels: ["enhancement"] **Alternatives considered** **Scope check** - + **Additional context** diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index ff14729..5aa7e84 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -14,13 +14,13 @@ ## Test plan - [ ] `python -m pytest -q` passes -- [ ] `python -m ruff check civiccore tests` passes +- [ ] `python -m ruff check townlight_core tests` passes - [ ] If touching migrations: idempotency tests pass and Gate 1/2/3 logic still holds for downstream consumers -- [ ] If touching public API in `civiccore.llm`: smoke test verifies symbols still importable +- [ ] If touching public API in `townlight_core.llm`: smoke test verifies symbols still importable ## Checklist - [ ] CHANGELOG.md updated under `[Unreleased]` -- [ ] If version bumped: pyproject.toml, civiccore/__init__.py, scripts/verify-release.sh fresh-venv asserts all aligned +- [ ] If version bumped: pyproject.toml, townlight_core/__init__.py, scripts/verify-release.sh fresh-venv asserts all aligned - [ ] No secrets committed - [ ] Linked issue: diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cb4a038..fd96686 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1,4 +1,4 @@ -name: civiccore CI +name: townlight-core CI on: pull_request: @@ -25,7 +25,7 @@ jobs: - name: Pre-pull pgvector image run: docker pull pgvector/pgvector:pg17 - - name: Install civiccore (editable, dev extras) + - name: Install townlight-core (editable, dev extras) run: | pip install --upgrade pip pip install -e .[dev] @@ -106,5 +106,5 @@ jobs: - name: Accessibility gate (no browser surface) run: | - echo "CivicCore exposes shared backend contracts and has no operator-facing browser surface in this repo." - echo "Per-PR axe gates run in CivicRecords AI, CivicClerk, CivicCode, and the CivicSuite launcher." + echo "Townlight Core exposes shared backend contracts and has no operator-facing browser surface in this repo." + echo "Per-PR axe gates run in CivicRecords AI, CivicClerk, CivicCode, and the Townlight launcher." diff --git a/.github/workflows/cleanroom.yml b/.github/workflows/cleanroom.yml index 7bfa077..7a8a1ab 100644 --- a/.github/workflows/cleanroom.yml +++ b/.github/workflows/cleanroom.yml @@ -1,4 +1,4 @@ -name: civiccore cleanroom +name: townlight-core cleanroom on: pull_request: @@ -7,8 +7,8 @@ on: - ".github/workflows/cleanroom.yml" - "cleanroom/**" - "scripts/cleanroom/**" - - "scripts/run-civiccore-cleanroom.sh" - - "civiccore/release_provenance.py" + - "scripts/run-townlight-core-cleanroom.sh" + - "townlight_core/release_provenance.py" - "tests/fixtures/release_provenance/**" - "tests/test_cleanroom_harness.py" - "docs/ops/cleanroom-harness.md" @@ -36,10 +36,10 @@ jobs: fetch-depth: 0 - name: Verify Docker is available run: docker version - - name: Run CivicCore cleanroom harness - run: bash scripts/run-civiccore-cleanroom.sh "$TARGET_COMMIT" "docs/evidence/co6-ci-${TARGET_COMMIT}" + - name: Run Townlight Core cleanroom harness + run: bash scripts/run-townlight-core-cleanroom.sh "$TARGET_COMMIT" "docs/evidence/co6-ci-${TARGET_COMMIT}" - name: Upload cleanroom evidence uses: actions/upload-artifact@v7 with: - name: civiccore-co6-cleanroom-${{ env.TARGET_COMMIT }} + name: townlight-core-co6-cleanroom-${{ env.TARGET_COMMIT }} path: docs/evidence/co6-ci-${{ env.TARGET_COMMIT }}/ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 941b3d0..f12c775 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -4,7 +4,7 @@ on: push: tags: - "v*" - - "civiccore-*-freeze" + - "townlight-core-*-freeze" workflow_dispatch: inputs: release_tag: @@ -33,7 +33,7 @@ jobs: with: python-version: "3.13" - - name: Cleanroom cache strip (scoped, CivicSuite-only) + - name: Cleanroom cache strip (scoped, Townlight-only) shell: bash run: | python - <<'PY' @@ -44,10 +44,10 @@ jobs: for rel in (".npm", ".cache/pip"): shutil.rmtree(os.path.join(runner_temp, rel), ignore_errors=True) PY - docker builder prune --all --force --filter "label=civicsuite-cleanroom=1" || true - docker network ls --filter "label=civicsuite-cleanroom=1" -q \ + docker builder prune --all --force --filter "label=townlight-cleanroom=1" || true + docker network ls --filter "label=townlight-cleanroom=1" -q \ | xargs -r docker network rm || true - docker volume ls --filter "label=civicsuite-cleanroom=1" -q \ + docker volume ls --filter "label=townlight-cleanroom=1" -q \ | xargs -r docker volume rm || true - name: Install published wheel from release URL @@ -55,22 +55,22 @@ jobs: run: | TAG="${{ inputs.release_tag }}" VERSION="${TAG#v}" - WHEEL_URL="https://github.com/CivicSuite/civiccore/releases/download/${TAG}/civiccore-${VERSION}-py3-none-any.whl" + WHEEL_URL="https://github.com/townlight/core/releases/download/${TAG}/townlight_core-${VERSION}-py3-none-any.whl" echo "Cleanroom wheel URL: ${WHEEL_URL}" python -m venv .cleanroom-venv . .cleanroom-venv/bin/activate python -m pip install --upgrade pip python -m pip install --no-cache-dir --force-reinstall "${WHEEL_URL}" TESTING=1 python - < release-notes.md <_VERSION = "X.Y.Z"` constants @@ -34,7 +34,7 @@ A grep hit is SHAPE-GUARD when ALL of these hold: - Updating X to the new version would pass trivially with no real coverage Examples: -- `assert "civiccore==1.0.0" not in dependencies` - asserts no `==` pinning, version-independent +- `assert "townlight_core==1.0.0" not in dependencies` - asserts no `==` pinning, version-independent - `assert "1.0.0.dev0" not in text` - asserts no stale dev marker, version-unrelated ### OWN-MODULE-VERSION - SKIP (do not edit during a dependency-bump sweep) @@ -72,7 +72,7 @@ The fix-forward bound is: changes must touch only `.github/workflows/`, `scripts ### CONTRACT-CHANGE - HALT AND REPORT - Any source code change required -- Any test asserting on dependency-removed behavior (e.g., civicclerk tests asserting on civiccore-removed `token_roles` field) - the auditor must approve the test update before the agent applies it +- Any test asserting on dependency-removed behavior (e.g., civicclerk tests asserting on townlight_core-removed `token_roles` field) - the auditor must approve the test update before the agent applies it - Any cross-module dependency conflict - Any failure whose root cause requires a design decision diff --git a/CHANGELOG.md b/CHANGELOG.md index c541379..4913cae 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,15 +1,53 @@ # Changelog -All notable changes to **civiccore** are documented here. Format follows +All notable changes to **townlight-core** (formerly **civiccore**) are +documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -CivicCore is the shared platform package for the -[CivicSuite](https://github.com/CivicSuite/civicsuite) open-source -municipal operations suite. Per the CivicCore Extraction Spec section 16, -breaking changes to the public API surface (Appendix A of that spec) ship -as MAJOR releases; new symbols or backward-compatible behavior ship as -MINOR; bug fixes ship as PATCH. +Townlight Core is the shared platform package for the +[Townlight](https://github.com/townlight/townlight) open-source +municipal operations suite (formerly CivicSuite; the CivicSuite org and its +repos moved to the townlight org on 2026-08-12). Per the CivicCore +Extraction Spec section 16, breaking changes to the public API surface +(Appendix A of that spec) ship as MAJOR releases; new symbols or +backward-compatible behavior ship as MINOR; bug fixes ship as PATCH. + +## [Unreleased] + +### Changed +- **Rebrand: CivicSuite -> Townlight.** Renamed the package from `civiccore` + to `townlight-core` (distribution name) / `townlight_core` (import path), + following the CivicSuite org and repo move to the townlight org on + 2026-08-12. This is a breaking change for anything that does + `import civiccore`, sets `CIVICCORE_*` environment variables, or reads the + `civiccore_version` / `civiccore_min_version` / `civiccore_locked` manifest + fields — see README.md and USER-MANUAL.md for the new import path and env + var names. +- Renamed `civiccore/` to `townlight_core/` and `civiccore-ui/` to + `townlight-core-ui/` (the latter is a frontend CSS/HTML asset directory, + not a Python package, so it kept kebab-case rather than adopting a + Python-style underscore). +- Updated CI workflows, the cleanroom Dockerfile/harness scripts, and the + release pipeline to build and verify `townlight_core-*` wheels going + forward. + +### Notes +- **Not changed, intentionally:** the Alembic version table name + (`alembic_version_civiccore`), the three shipped migration revision IDs + (`civiccore_0001_baseline_v1`, `civiccore_0002_llm`, + `civiccore_0003_local_task_queue`) and their file names, the + `civiccore_local_tasks` table name, and the `consumer_app='civiccore'` + prompt-template DB default (`CIVICCORE_DEFAULT_APP`). These are already + persisted in every consuming module's database; renaming them here would + silently break existing deployments with no migration path. Historical/ + evidence content (`docs/audits/`, `docs/ops/`, `docs/evidence/`, + `docs/qa/`, `docs/adr/`, `sprint-phase2-evidence/`, dated release + attestations, and this changelog's own pre-2026-08-12 entries) also keeps + the old names, since they describe or verify things as they actually were. +- No functional change to any shipped behavior; this is a packaging/branding + rename only. `v1.2.1` remains the latest published release and is + unaffected (its wheel is still named `civiccore-1.2.1-py3-none-any.whl`). ## [1.2.1] - 2026-07-04 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index f813ffb..2e592cc 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -6,7 +6,7 @@ The full text is available at the link above. ## Reporting -Report concerns about contributor conduct via [GitHub private security advisories](https://github.com/CivicSuite/civiccore/security/advisories/new) or by opening a private discussion with a maintainer. +Report concerns about contributor conduct via [GitHub private security advisories](https://github.com/townlight/core/security/advisories/new) or by opening a private discussion with a maintainer. ## Scope diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2106138..5301576 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,18 @@ -# Contributing to CivicCore +# Contributing to Townlight Core -Thanks for considering a contribution. CivicCore is the shared platform -package for the [CivicSuite](https://github.com/CivicSuite/civicsuite) +Thanks for considering a contribution. Townlight Core is the shared platform +package for the [Townlight](https://github.com/townlight/townlight) open-source municipal operations suite — every line of code here is -consumed by every CivicSuite module, so the bar is high and the surface +consumed by every Townlight module, so the bar is high and the surface is deliberately small. ## Status -CivicCore is at v0.1 (Phase 0 — package skeleton). Functional code lands -in Phase 1 and beyond per the CivicCore Extraction Spec section 12. If +Townlight Core is at v0.1 (Phase 0 — package skeleton). Functional code lands +in Phase 1 and beyond per the Townlight Core Extraction Spec section 12. If you want to contribute today, the most useful work is: -- Reviewing the Extraction Spec (in CivicSuite/civicsuite) and filing +- Reviewing the Extraction Spec (in Townlight/townlight) and filing issues against ambiguous wording. - Building a Phase 1 prototype against the auth + audit subsystem contracts in Appendix A of the spec. @@ -21,10 +21,10 @@ you want to contribute today, the most useful work is: ## Where does my bug go? (decision tree) -CivicSuite is a multi-repo project. Filing a bug in the wrong place -delays the fix. This decision tree mirrors the one in every CivicSuite -repo's `CONTRIBUTING.md`, written here from CivicCore's perspective. It -is a copy of the mitigation guidance from the CivicCore Extraction Spec +Townlight is a multi-repo project. Filing a bug in the wrong place +delays the fix. This decision tree mirrors the one in every Townlight +repo's `CONTRIBUTING.md`, written here from Townlight Core's perspective. It +is a copy of the mitigation guidance from the Townlight Core Extraction Spec section 18 ("Contributor confusion about where to file a bug"). 1. **Is the bug in shared platform infrastructure?** @@ -33,28 +33,28 @@ section 18 ("Contributor confusion about where to file a bug"). notification service, onboarding, the municipal systems catalog, the 50-state exemption engine, sovereignty verification scripts, shared ORM models, or shared-table Alembic migrations. - ➜ **File it here:** https://github.com/CivicSuite/civiccore/issues + ➜ **File it here:** https://github.com/townlight/core/issues 2. **Is the bug in records-request workflow, response-letter generation, fee schedules, the records dashboards, or any records-specific UI page?** ➜ **File it in CivicRecords AI:** - https://github.com/CivicSuite/civicrecords-ai/issues + https://github.com/townlight/civicrecords-ai/issues 3. **Is the bug in meeting agendas, minutes, voting, or the clerk workflow?** ➜ **File it in CivicClerk** (when it exists). Until then, file it in - the CivicSuite umbrella so we can route it. + the Townlight umbrella so we can route it. 4. **Is the bug about how the modules fit together, the suite-wide roadmap, the module catalog, or cross-module documentation?** - ➜ **File it in the CivicSuite umbrella:** - https://github.com/CivicSuite/civicsuite/issues + ➜ **File it in the Townlight umbrella:** + https://github.com/townlight/townlight/issues 5. **Are you reporting a security vulnerability?** Do not file it as a public issue. See "Security advisories" below. -If you are unsure — file it in the CivicSuite umbrella repo. A +If you are unsure — file it in the Townlight umbrella repo. A maintainer will move it to the right place. Better here than nowhere. @@ -64,7 +64,7 @@ nowhere. Requirements: -- Python `>=3.11` (CivicCore widens past civicrecords-ai's 3.12 floor +- Python `>=3.11` (Townlight Core widens past civicrecords-ai's 3.12 floor because it is a shared library). - Git. - A POSIX-ish shell or PowerShell. The package itself is OS-agnostic. @@ -72,8 +72,8 @@ Requirements: Clone and install in editable mode with the dev extras: ```bash -git clone https://github.com/CivicSuite/civiccore.git -cd civiccore +git clone https://github.com/townlight/core.git +cd core python -m venv .venv # macOS / Linux: source .venv/bin/activate @@ -101,7 +101,7 @@ python scripts/verify/verify_no_telemetry.py # planned ## Code standards - Match existing patterns. Where a pattern is missing, follow the - conventions in `civicrecords-ai/backend/app/` — CivicCore is being + conventions in `civicrecords-ai/backend/app/` — Townlight Core is being extracted from that codebase and consistency makes the migration reviewable. - Type hints on every public function. `mypy` strictness ratchets up @@ -109,8 +109,8 @@ python scripts/verify/verify_no_telemetry.py # planned - `ruff` with the project config (`pyproject.toml`). Run `ruff check` and `ruff format` before submitting. - Async/await consistently for any I/O path. -- No telemetry. No outbound network calls at runtime. CivicCore inherits - the CivicSuite sovereignty stance unmodified. +- No telemetry. No outbound network calls at runtime. Townlight Core inherits + the Townlight sovereignty stance unmodified. ## Tests @@ -122,7 +122,7 @@ state. ## Semantic versioning discipline -Per the CivicCore Extraction Spec section 16, the public API surface +Per the Townlight Core Extraction Spec section 16, the public API surface listed in Appendix A is stable across the v0.x series: - **MAJOR** — any breaking change to the Appendix A surface (removed @@ -135,14 +135,14 @@ listed in Appendix A is stable across the v0.x series: When you bump the version, update it in every location in the same commit (currently: `pyproject.toml` `[project].version` and -`civiccore/__init__.py` `__version__`). +`townlight_core/__init__.py` `__version__`). ## Security advisories Do not file security issues as public GitHub issues. Use GitHub's private vulnerability reporting on this repository (Security tab → Report a vulnerability), or email the maintainer listed on the -[CivicSuite umbrella repo](https://github.com/CivicSuite/civicsuite) +[Townlight umbrella repo](https://github.com/townlight/townlight) governance page. We will acknowledge within seven days and coordinate a fix and disclosure timeline with you. diff --git a/LICENSE b/LICENSE index 1573edf..c550169 100644 --- a/LICENSE +++ b/LICENSE @@ -186,7 +186,7 @@ same "printed page" as the copyright notice for easier identification within third-party archives. - Copyright 2026 Scott Converse and CivicSuite contributors + Copyright 2026 Scott Converse and Townlight contributors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. @@ -202,7 +202,7 @@ --- -Copyright 2026 Scott Converse and CivicSuite contributors +Copyright 2026 Scott Converse and Townlight contributors Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. diff --git a/README.md b/README.md index 0c84503..7c9f43f 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,16 @@ -# CivicCore +# Townlight Core Shared platform package for the -[CivicSuite](https://github.com/CivicSuite/civicsuite) open-source -municipal operations suite. +[Townlight](https://github.com/townlight/townlight) open-source +municipal operations suite (formerly CivicSuite; the CivicSuite org and its +repos moved to the townlight org on 2026-08-12). ## What this is -CivicCore is the Python package every CivicSuite module depends on for +Townlight Core is the Python package every Townlight module depends on for shared platform plumbing. **What ships today:** the migration runner plus `civiccore_0001_baseline_v1` shared-schema baseline, a shared SQLAlchemy -declarative `Base`, the `civiccore.llm` module, hash-chained audit +declarative `Base`, the `townlight_core.llm` module, hash-chained audit primitives, source/provenance metadata contracts, offline import/export manifest schemas, static export-bundle helpers, local city profile configuration, small auth helpers for downstream FastAPI services, @@ -32,36 +33,36 @@ actionable warning codes, plus shared cron schedule validation helpers for module background jobs. **Still planned extraction targets (placeholder packages exist; not yet -implemented today):** `civiccore.catalog`, `civiccore.exemptions` +implemented today):** `townlight_core.catalog`, `townlight_core.exemptions` (50-state public-records exemption engine), -`civiccore.scaffold`. `civiccore.ingest` now ships reusable +`townlight_core.scaffold`. `townlight_core.ingest` now ships reusable discovery/fetch contracts, cited-source validation helpers, and the shared document ingestion pipeline. It does not ship a worker scheduler/runtime. -`civiccore.onboarding` now ships storage-neutral +`townlight_core.onboarding` now ships storage-neutral profile interview helpers, but not a web onboarding UI or persistence -router. `civiccore.search` now ships normalization and +router. `townlight_core.search` now ships normalization and fusion helpers, but not a full search engine or indexer. -`civiccore.notifications` now ships notice deadline and compliance +`townlight_core.notifications` now ships notice deadline and compliance helpers, but not delivery queues or outbound notification orchestration. -`civiccore.platform` now ships the Windows-local desktop contracts for module +`townlight_core.platform` now ships the Windows-local desktop contracts for module manifests, install-profile validation, operator health summaries, durable local task envelopes, backup/restore manifests, and installer/runtime action results. It also ships the PostgreSQL-backed `civiccore_local_tasks` migration, async -queue helpers, and `python -m civiccore.tasks.worker` entry point for the local -desktop worker. Product modules still own task handlers and UI, while CivicCore +queue helpers, and `python -m townlight_core.tasks.worker` entry point for the local +desktop worker. Product modules still own task handlers and UI, while Townlight Core owns shared validation, queue state, retry semantics, and plain-English operator state. -`civiccore.verification` now ships the first release-evidence helper +`townlight_core.verification` now ships the first release-evidence helper surface, while sovereignty verification remains future work. -`civiccore.connectors` now also ships shared local-payload import +`townlight_core.connectors` now also ships shared local-payload import normalization helpers, live-sync retry/circuit-breaker primitives, and source-list status projection helpers for supported agenda platforms, while -`civiccore.security` now ships shared connector-host validation, +`townlight_core.security` now ships shared connector-host validation, startup config validation, and encrypted JSON envelope helpers for secret-bearing config. -`civiccore.scheduling` now ships storage-neutral cron validation and next-run +`townlight_core.scheduling` now ships storage-neutral cron validation and next-run helpers, but not a scheduler runtime or task queue. Credential orchestration, vendor-specific network adapters, and vendor write-back remain unshipped. -`civiccore.release_provenance` now uses the attestation trust model for release +`townlight_core.release_provenance` now uses the attestation trust model for release verification: Git tags are treated as release pointers, while `release-attestation.json` plus its Sigstore/cosign bundle are the verifiable trust artifacts. The exact workflow identity is pinned per repo and per tag; @@ -73,7 +74,7 @@ Phase work and must not be relied on by downstream modules until they ship. ## Status -**v1.2.1 is the current CivicCore downstream productization line.** It carries +**v1.2.1 is the current Townlight Core downstream productization line.** It carries the shared document-ingestion pipeline used by the city-core release train, the CO-7 freeze-line trust anchor, the CO-8 procurement evidence pack, and the CO-9 closeout trail for modules that need a procurement-grade platform pin. @@ -98,20 +99,20 @@ manifests, on top of shared persisted audit-log hash and verification helpers fo database-backed module audit rows on top of shared trusted-header auth config loading and proxy-source enforcement helpers on top of shipped trusted-header auth helpers on top of shipped -`civiccore.ingest` discovery/fetch, cited-source validation, and document-ingestion pipeline on top of shipped -`civiccore.security` connector host-validation, startup config validation, and encrypted-config helpers on top of shipped -`civiccore.onboarding` profile interview helpers on top of shipped -`civiccore.notifications` notice deadline planning and publication -compliance helpers on top of the shipped `civiccore.connectors` -local-first import helpers, the shipped `civiccore.search` helper +`townlight_core.ingest` discovery/fetch, cited-source validation, and document-ingestion pipeline on top of shipped +`townlight_core.security` connector host-validation, startup config validation, and encrypted-config helpers on top of shipped +`townlight_core.onboarding` profile interview helpers on top of shipped +`townlight_core.notifications` notice deadline planning and publication +compliance helpers on top of the shipped `townlight_core.connectors` +local-first import helpers, the shipped `townlight_core.search` helper surface for deterministic text matching, permission-aware access checks, and reciprocal-rank-fusion, the -shipped `civiccore.verification` release-evidence helpers, the shipped -`civiccore.auth` optional bearer resolver for mixed public/staff +shipped `townlight_core.verification` release-evidence helpers, the shipped +`townlight_core.auth` optional bearer resolver for mixed public/staff endpoints, and the shared audit, provenance, manifest, export-bundle, and city profile primitives needed for the first production-depth -CivicSuite workflows. -`v0.2.0` shipped the `civiccore.llm` module: +Townlight workflows. +`v0.2.0` shipped the `townlight_core.llm` module: provider abstraction (Ollama / OpenAI / Anthropic), prompt template engine with a 3-step override resolver, model registry service + admin router, context utilities with prompt-injection defense, and a Pydantic-validated @@ -138,17 +139,23 @@ shared-schema baseline extracted from CivicRecords AI). From the current GitHub release wheel (`v1.2.1`): ```bash -pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl +pip install https://github.com/townlight/core/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl ``` +`v1.2.1` predates this rename, so its wheel filename is still +`civiccore-1.2.1-py3-none-any.whl` (a real, already-published artifact — the +filename is not rewritten after the fact). The next release cut from this +package will ship as `townlight_core--py3-none-any.whl` under the +`townlight-core` distribution name. + Each GitHub release also publishes `SHA256SUMS.txt` alongside the wheel and sdist. Verify the checksum before promoting a release artifact into a downstream module or internal package mirror. ### Release Provenance -CivicCore now carries the canonical CivicSuite release-provenance gate in -`civiccore.release_provenance`. The gate exists because GitHub release pages can +Townlight Core now carries the canonical Townlight release-provenance gate in +`townlight_core.release_provenance`. The gate exists because GitHub release pages can show the target commit as "Verified" even when the release tag is lightweight or the annotated tag object is unsigned. Treat the release-page badge as a commit signal only; use `scripts/verify-release-provenance.py` and @@ -159,7 +166,7 @@ shared document-ingestion pipeline used by the city-core release train. The original `v1.0` release remains historical and superseded. `v0.22.1` remains the first attested baseline release, and `civiccore-m1-freeze` remains the CO-7 freeze-line tag downstream modules use as their initial trust anchor. -`v0.22.0` and earlier CivicCore releases predate the Sigstore attestation +`v0.22.0` and earlier Townlight Core releases predate the Sigstore attestation baseline and are retained for historical installs only. Their Tier 1 status is published in [`docs/ops/civiccore-tier1-retrofit-ledger.md`](docs/ops/civiccore-tier1-retrofit-ledger.md). The operative historical disclosure is published in @@ -185,12 +192,12 @@ recorded in that ledger. For development from a clone: ```bash -git clone https://github.com/CivicSuite/civiccore.git -cd civiccore +git clone https://github.com/townlight/core.git +cd core pip install -e .[dev] ``` -PyPI publication can come later; CivicCore is distributed as versioned +PyPI publication can come later; Townlight Core is distributed as versioned GitHub release artifacts so CivicRecords AI can stop depending on a Git SHA pin. The tag-driven release workflow runs `scripts/verify-release.sh` before publishing so the shipped artifact has already passed pytest, ruff, @@ -199,10 +206,10 @@ test. ## LLM providers -CivicCore exposes a pluggable LLM provider abstraction for downstream apps. Three providers ship built-in: +Townlight Core exposes a pluggable LLM provider abstraction for downstream apps. Three providers ship built-in: ```python -from civiccore.llm.providers import ( +from townlight_core.llm.providers import ( LLMProvider, # ABC register_provider, # decorator for adding new providers get_provider, # construct a provider by name @@ -224,17 +231,17 @@ Optional cloud-provider SDKs are needed only if you instantiate the correspondin pip install openai # required for OpenAIProvider pip install anthropic # required for AnthropicProvider -# Extras shorthand (works once civiccore is published to PyPI): -pip install civiccore[openai] -pip install civiccore[anthropic] +# Extras shorthand (works once townlight-core is published to PyPI): +pip install townlight-core[openai] +pip install townlight-core[anthropic] ``` Ollama needs no extra (uses httpx, already a base dependency). -Third-party providers register via the public decorator without modifying civiccore source: +Third-party providers register via the public decorator without modifying townlight_core source: ```python -from civiccore.llm.providers import LLMProvider, register_provider +from townlight_core.llm.providers import LLMProvider, register_provider @register_provider("my_provider") class MyProvider(LLMProvider): @@ -243,10 +250,10 @@ class MyProvider(LLMProvider): ## LLM templates -CivicCore exposes a prompt-template rendering and override-resolution layer for downstream apps. +Townlight Core exposes a prompt-template rendering and override-resolution layer for downstream apps. ```python -from civiccore.llm.templates import ( +from townlight_core.llm.templates import ( PromptTemplate, # ORM PromptTemplateCreate, # Pydantic schemas PromptTemplateRead, @@ -277,10 +284,10 @@ Callers passing `consumer_app="civiccore"` skip both override steps (1 and 2) an ## LLM context utilities and structured output -CivicCore exposes context-budgeting and structured-output helpers at the package root: +Townlight Core exposes context-budgeting and structured-output helpers at the package root: ```python -from civiccore.llm import ( +from townlight_core.llm import ( TokenBudget, ContextBlock, estimate_tokens, count_tokens, sanitize_for_llm, assemble_context, blocks_to_prompt, DEFAULT_CONTEXT_WINDOW, @@ -312,11 +319,11 @@ Per ADR-0004: token counting is context-window math; no cost tracking, no spend ## Audit, provenance, manifests, exports, and city profiles -The current CivicCore development line adds storage-neutral primitives +The current Townlight Core development line adds storage-neutral primitives for production-depth municipal workflows: ```python -from civiccore import ( +from townlight_core import ( AuditActor, AuditSubject, AuditHashChain, PersistedAuditLogEntry, compute_persisted_audit_hash, verify_persisted_audit_chain, @@ -360,12 +367,12 @@ adapters, worker execution, legal determinations, or vendor write-back. ## Windows-local platform contracts -`civiccore.platform` exposes the shared contracts and queue helpers the -CivicSuite Windows desktop shell uses to keep future modules pluggable without +`townlight_core.platform` exposes the shared contracts and queue helpers the +Townlight Windows desktop shell uses to keep future modules pluggable without making clerks learn infrastructure: ```python -from civiccore.platform import ( +from townlight_core.platform import ( ModuleManifest, build_module_registry, PlatformHealthCheck, @@ -381,14 +388,14 @@ from civiccore.platform import ( ``` For the `windows_local` install profile, module manifests cannot require -Docker, WSL, Linux shell setup, or a terminal-only operator path. CivicCore also +Docker, WSL, Linux shell setup, or a terminal-only operator path. Townlight Core also ships task envelopes, a durable PostgreSQL task table, async queue helpers, and a worker CLI so downstream modules share retry, health, checksum, and restore-safety semantics while registering their own task handlers. ## Document ingestion -`civiccore.ingest` owns the shared document-ingestion path for downstream +`townlight_core.ingest` owns the shared document-ingestion path for downstream modules. It exposes parser dispatch plus `register_handler()`, `ingest_file()`, and `ingest_bytes()` entry points; stores parsed files in the baseline `documents` table; writes sentence-aware chunks to `document_chunks`; and @@ -397,7 +404,7 @@ persists 768-dimensional local Ollama embeddings through pgvector. ```python from pathlib import Path -from civiccore.ingest import DataSource, SourceType, ingest_file +from townlight_core.ingest import DataSource, SourceType, ingest_file source = DataSource( name="Longmont Code of Ordinances proof corpus", @@ -424,12 +431,12 @@ and wrote 1,789 768-dimensional `nomic-embed-text` embeddings. ## Live connector sync primitives -CivicCore ships the storage-neutral pieces of the CivicRecords AI sync pattern -so every CivicSuite module can share one retry and circuit-breaker contract +Townlight Core ships the storage-neutral pieces of the CivicRecords AI sync pattern +so every Townlight module can share one retry and circuit-breaker contract without inheriting product-specific tables, credentials, or vendor adapters. ```python -from civiccore.connectors import ( +from townlight_core.connectors import ( SyncCircuitState, SyncRunResult, apply_sync_run_result, @@ -456,7 +463,7 @@ source-list projection instead of reimplementing it. ## Auth helper -`civiccore.auth` now exposes small auth helpers for downstream FastAPI +`townlight_core.auth` now exposes small auth helpers for downstream FastAPI services that need to protect non-public internal endpoints or support mixed public/staff routes without taking on a full first-party identity-provider dependency. That surface now includes shared @@ -467,7 +474,7 @@ addition to bearer-token, trusted-header, and staff-key role checks. from fastapi import Depends from fastapi.security import HTTPBearer -from civiccore.auth import ( +from townlight_core.auth import ( authorize_bearer_roles, authorize_trusted_header_roles, resolve_optional_bearer_roles, @@ -530,25 +537,25 @@ tokens to role strings or role lists: } ``` -If the bearer-token config is missing or malformed, CivicCore raises an +If the bearer-token config is missing or malformed, Townlight Core raises an actionable `503`; missing or invalid bearer headers return `401`; tokens without an allowed role return `403`. Trusted-header helpers return actionable `401` and `403` responses when the proxy assertion is missing, malformed, or underprivileged. The optional resolvers return `None` for anonymous callers, which lets public endpoints stay public until a caller actually presents a bearer token or arrives through a trusted proxy. -`staff_key_gate()` preserves the existing CivicSuite module convention of +`staff_key_gate()` preserves the existing Townlight module convention of `X-Civic*-Role: staff` plus `X-Civic*-Staff-Key`, fails closed when the configured environment variable is missing, and compares submitted keys with `hmac.compare_digest`. ## Onboarding helper -`civiccore.onboarding` now ships shared storage-neutral helpers for +`townlight_core.onboarding` now ships shared storage-neutral helpers for interview-style city-profile onboarding flows: ```python -from civiccore.onboarding import ( +from townlight_core.onboarding import ( DEFAULT_PROFILE_FIELDS, compute_onboarding_status, next_profile_prompt, @@ -572,14 +579,14 @@ router integration, and persistence orchestration remain future work. ## Scheduling helper -`civiccore.scheduling` exposes the shared cron expression contract used by -module background jobs. `civiccore.platform` exposes the local task envelope, +`townlight_core.scheduling` exposes the shared cron expression contract used by +module background jobs. `townlight_core.platform` exposes the local task envelope, PostgreSQL queue helpers, and retry contract. Modules keep their own task handlers, but should reuse these helpers so one-minute accidental or adversarial -schedules and task retry behavior are handled consistently across CivicSuite. +schedules and task retry behavior are handled consistently across Townlight. ```python -from civiccore.scheduling import compute_next_sync_at, validate_cron_expression +from townlight_core.scheduling import compute_next_sync_at, validate_cron_expression validate_cron_expression("*/5 * * * *") next_run = compute_next_sync_at("0 2 * * *", last_sync_at=None) @@ -587,7 +594,7 @@ next_run = compute_next_sync_at("0 2 * * *", last_sync_at=None) ## Verification helper -`civiccore.verification` now ships a small browser-evidence helper for +`townlight_core.verification` now ships a small browser-evidence helper for current-facing release pages. It binds a release screenshot manifest to the normalized content hash of a rendered source file, which keeps browser QA evidence honest across Windows and Linux checkouts. @@ -595,7 +602,7 @@ browser QA evidence honest across Windows and Linux checkouts. ```python from pathlib import Path -from civiccore.verification import validate_release_browser_evidence +from townlight_core.verification import validate_release_browser_evidence result = validate_release_browser_evidence( repo_root=Path("."), @@ -607,10 +614,10 @@ print(result.reviewed_at) ## Public API surface -`civiccore.llm` exposes a single import surface for downstream apps: +`townlight_core.llm` exposes a single import surface for downstream apps: ```python -from civiccore.llm import ( +from townlight_core.llm import ( # Providers LLMProvider, register_provider, get_provider, list_providers, OllamaProvider, OpenAIProvider, AnthropicProvider, @@ -633,18 +640,19 @@ from civiccore.llm import ( The full enumerated list — stable across the v0.x series per the spec's semver policy — is also published in **Appendix A of the CivicCore -Extraction Spec** in -[CivicSuite/civicsuite](https://github.com/CivicSuite/civicsuite). +Extraction Spec** (the extraction predates this rename; the document itself +is historical) in +[townlight/townlight](https://github.com/townlight/townlight). ## Compatibility -Every CivicSuite module's README declares its CivicCore dependency contract. +Every Townlight module's README declares its Townlight Core dependency contract. Current v0.1.0 module foundations pin older civiccore lines. Production-depth -consumers should move only to the released CivicCore version recorded in their +consumers should move only to the released Townlight Core version recorded in their compatibility matrix. The suite-wide compatibility matrix — which -module versions work with which CivicCore versions — is maintained at -[CivicSuite/civicsuite/docs/compatibility/](https://github.com/CivicSuite/civicsuite/tree/main/docs/compatibility). +module versions work with which Townlight Core versions — is maintained at +[townlight/townlight/docs/compatibility/](https://github.com/townlight/townlight/tree/main/docs/compatibility). ## License @@ -653,4 +661,4 @@ module versions work with which CivicCore versions — is maintained at ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md), including the decision tree for -where to file a bug across the CivicSuite multi-repo layout. +where to file a bug across the Townlight multi-repo layout. diff --git a/README.txt b/README.txt index 462a79c..5528b52 100644 --- a/README.txt +++ b/README.txt @@ -1,53 +1,54 @@ -CivicCore -========= +Townlight Core +============== -Shared platform library for the CivicSuite open-source municipal operations -suite. https://github.com/CivicSuite/civicsuite +Shared platform library for the Townlight open-source municipal operations +suite (formerly CivicSuite; the CivicSuite org and its repos moved to the +townlight org on 2026-08-12). https://github.com/townlight/townlight What this is ------------ -CivicCore is the Python library every CivicSuite module depends on for shared +Townlight Core is the Python library every Townlight module depends on for shared platform plumbing. It is not an end-user municipal app. What ships in the current development line: - - civiccore.migrations - migration runner with idempotent guards plus the + - townlight_core.migrations - migration runner with idempotent guards plus the civiccore_0001_baseline_v1 shared-schema baseline and civiccore_0002_llm. - - civiccore.db - shared SQLAlchemy declarative Base. - - civiccore.llm - providers, prompt templates, model registry, context + - townlight_core.db - shared SQLAlchemy declarative Base. + - townlight_core.llm - providers, prompt templates, model registry, context utilities, and structured output. - - civiccore.audit - hash-chained audit primitives plus persisted audit-log + - townlight_core.audit - hash-chained audit primitives plus persisted audit-log hash and verification helpers. - - civiccore.provenance - source/provenance metadata contracts. - - civiccore.connectors - offline import/export manifest schemas, + - townlight_core.provenance - source/provenance metadata contracts. + - townlight_core.connectors - offline import/export manifest schemas, local-first import helpers for supported agenda-platform payloads, vendor delta request planning, storage-neutral live-sync retry/circuit-breaker primitives, and source-list status projections. - - civiccore.testing - no-network mock-city proof contracts for supported + - townlight_core.testing - no-network mock-city proof contracts for supported agenda vendors, municipal OIDC, and backup-retention/off-host readiness. - - civiccore.security - connector host validation, startup config + - townlight_core.security - connector host validation, startup config validation, and encrypted JSON envelope helpers for secret-bearing config. - - civiccore.exports - static export-bundle manifest and checksum helpers. - - civiccore.city_profile - local city/deployment configuration models. - - civiccore.auth - bearer-token role helpers for protected or mixed + - townlight_core.exports - static export-bundle manifest and checksum helpers. + - townlight_core.city_profile - local city/deployment configuration models. + - townlight_core.auth - bearer-token role helpers for protected or mixed public/staff FastAPI routes. - - civiccore.verification - content-bound browser release-evidence helpers. - - civiccore.search - deterministic text normalization, matching, and + - townlight_core.verification - content-bound browser release-evidence helpers. + - townlight_core.search - deterministic text normalization, matching, and reciprocal-rank-fusion helpers. - - civiccore.notifications - notice deadline planning and publication + - townlight_core.notifications - notice deadline planning and publication compliance helpers with actionable warning codes. - - civiccore.scheduling - cron validation and next-run helpers for module + - townlight_core.scheduling - cron validation and next-run helpers for module background jobs. - - civiccore.ingest - shared discovery/fetch contracts, cited-source + - townlight_core.ingest - shared discovery/fetch contracts, cited-source validation helpers, and the document-ingestion pipeline for PDF, DOCX, XLSX, CSV, EML, HTML, and text files with sentence-aware chunking, local Ollama embeddings, and pgvector-backed documents/document_chunks storage. Still planned extraction targets: - civiccore.catalog, civiccore.exemptions, civiccore.scaffold. - civiccore.onboarding now ships storage-neutral profile interview + townlight_core.catalog, townlight_core.exemptions, townlight_core.scaffold. + townlight_core.onboarding now ships storage-neutral profile interview helpers, but not a web onboarding UI or persistence router. Credential storage, vendor-specific network adapters, vendor write-back, @@ -57,7 +58,7 @@ determinations are still not shipped platform behaviors. Status ------ -v1.2.1 is the current CivicCore downstream productization line. It carries the +v1.2.1 is the current Townlight Core downstream productization line. It carries the shared document-ingestion pipeline used by the city-core release train, the CO-7 freeze-line trust anchor, the CO-8 procurement evidence pack, and the CO-9 closeout trail. @@ -70,16 +71,21 @@ verification helpers, shared search helpers, local-first connector import helpers, and notice deadline/compliance helpers on top of the audit, provenance, manifest, export-bundle, city-profile, migration, and LLM primitives. v0.2.0 shipped the -civiccore.llm module. v0.1.0 shipped the migration baseline. +townlight_core.llm module. v0.1.0 shipped the migration baseline. Install ------- From the current published GitHub release wheel: - pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl + pip install https://github.com/townlight/core/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl -CivicCore is distributed as versioned GitHub release artifacts (not on PyPI). +(v1.2.1 predates this rename, so its wheel filename is still +civiccore-1.2.1-py3-none-any.whl -- a real, already-published artifact. The +next release will ship as townlight_core--py3-none-any.whl under the +townlight-core distribution name.) + +Townlight Core is distributed as versioned GitHub release artifacts (not on PyPI). Each release publishes SHA256SUMS.txt alongside the wheel and sdist. Verify checksums before promoting an artifact downstream. v1.2.1 is the current published downstream productization line and includes the shared @@ -88,14 +94,14 @@ earlier releases are retained for historical installs only. For development from a clone: - git clone https://github.com/CivicSuite/civiccore.git - cd civiccore + git clone https://github.com/townlight/core.git + cd core pip install -e .[dev] Public API surface (high level) ------------------------------- - civiccore.llm + townlight_core.llm LLMProvider, register_provider, get_provider, list_providers OllamaProvider, OpenAIProvider, AnthropicProvider, build_provider PromptTemplate, RenderedPrompt, render_template, resolve_template @@ -103,16 +109,16 @@ Public API surface (high level) TokenBudget, ContextBlock, assemble_context, blocks_to_prompt sanitize_for_llm, StructuredOutput, StructuredOutputFailure - civiccore.audit + townlight_core.audit AuditActor, AuditSubject, AuditEvent, AuditHashChain, PersistedAuditLogEntry, compute_persisted_audit_hash, verify_persisted_audit_chain - civiccore.provenance + townlight_core.provenance SourceKind, SourceReference, CitationTarget, DocumentMetadata, ProvenanceBundle - civiccore.connectors / civiccore.exports + townlight_core.connectors / townlight_core.exports ConnectorImportError, ImportedAgendaItem, ImportedMeeting, SUPPORTED_CONNECTORS, import_meeting_payload, SyncCircuitPolicy, SyncCircuitState, SyncRunResult, SyncSourceStatus, @@ -122,30 +128,30 @@ Public API surface (high level) ExportBundle, BundleFile, write_manifest, build_sha256sums, validate_bundle - civiccore.city_profile + townlight_core.city_profile CityProfile, DepartmentProfile, DeploymentProfile, ModuleEnablement, load_city_profile - civiccore.onboarding + townlight_core.onboarding OnboardingField, OnboardingProgress, DEFAULT_PROFILE_FIELDS, parse_profile_answer, compute_onboarding_status, completed_profile_fields, next_profile_prompt - civiccore.migrations / civiccore.db + townlight_core.migrations / townlight_core.db Migration runner, civiccore_0001_baseline_v1 shared schema, and Base - civiccore.scheduling + townlight_core.scheduling validate_cron_expression, min_interval_minutes, compute_next_sync_at Compatibility ------------- Current v0.1.0 module foundations still pin older civiccore lines. -Production-depth consumers should move only to the released CivicCore version +Production-depth consumers should move only to the released Townlight Core version recorded in their compatibility matrix. The suite-wide compatibility matrix is maintained at: -https://github.com/CivicSuite/civicsuite/tree/main/docs/compatibility +https://github.com/townlight/townlight/tree/main/docs/compatibility License ------- @@ -156,9 +162,9 @@ Contributing ------------ See CONTRIBUTING.md, including the decision tree for where to file a bug -across the CivicSuite multi-repo layout. +across the Townlight multi-repo layout. Source ------ -https://github.com/CivicSuite/civiccore +https://github.com/townlight/core diff --git a/SECURITY.md b/SECURITY.md index 15907cc..c1060bf 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -7,7 +7,7 @@ | 0.2.x | Yes | | < 0.2 | No | -CivicCore is in pre-1.0; only the latest minor (`0.2.x`) receives security +Townlight Core is in pre-1.0; only the latest minor (`0.2.x`) receives security fixes. Once we cut `0.3.0`, support for `0.2.x` ends. ## Reporting a vulnerability @@ -17,17 +17,17 @@ fixes. Once we cut `0.3.0`, support for `0.2.x` ends. Two preferred channels, in order: 1. **GitHub Security Advisory** — open a private security advisory at - https://github.com/CivicSuite/civiccore/security/advisories/new. This + https://github.com/townlight/core/security/advisories/new. This is the fastest path; it is private to maintainers until disclosure. 2. **Email** — if you cannot use the advisory flow, email the maintainer - listed at https://github.com/CivicSuite/civiccore (the `Maintained by` - link in the README) with subject prefix `[civiccore-security]`. + listed at https://github.com/townlight/core (the `Maintained by` + link in the README) with subject prefix `[townlight_core-security]`. ### What to include - A description of the vulnerability and where it lives in the codebase. - A reproducer (minimal code or steps). -- The civiccore version affected. +- The townlight_core version affected. - Your assessment of impact (data exposure, privilege escalation, denial of service, etc.). - Whether you believe downstream consumers (records-ai, future modules) @@ -46,7 +46,7 @@ Two preferred channels, in order: In scope: -- Code in `civiccore/`. +- Code in `townlight_core/`. - Build / packaging configuration that ships in the release artifact. - The migration runner and any SQL it generates. - LLM provider abstraction (sanitization, prompt-injection defense, secret diff --git a/SUPPORT.md b/SUPPORT.md index af9853e..a0a7c5d 100644 --- a/SUPPORT.md +++ b/SUPPORT.md @@ -1,27 +1,27 @@ # Support -civiccore is a shared platform library for the CivicSuite product family. Support is community-driven via GitHub. +townlight_core is a shared platform library for the Townlight product family. Support is community-driven via GitHub. ## Where to ask | Question type | Where | |---|---| -| Usage / how-to | [GitHub Discussions](https://github.com/CivicSuite/civiccore/discussions) | -| Bugs and defects | [GitHub Issues](https://github.com/CivicSuite/civiccore/issues) — use the bug report template | -| Feature requests | [GitHub Issues](https://github.com/CivicSuite/civiccore/issues) — use the feature request template | -| Documentation gaps | [GitHub Issues](https://github.com/CivicSuite/civiccore/issues) — use the documentation template | +| Usage / how-to | [GitHub Discussions](https://github.com/townlight/core/discussions) | +| Bugs and defects | [GitHub Issues](https://github.com/townlight/core/issues) — use the bug report template | +| Feature requests | [GitHub Issues](https://github.com/townlight/core/issues) — use the feature request template | +| Documentation gaps | [GitHub Issues](https://github.com/townlight/core/issues) — use the documentation template | | Security reports | See [SECURITY.md](SECURITY.md) — do not open public issues for security concerns | ## Before opening an issue 1. Check the [README](README.md), [USER-MANUAL](USER-MANUAL.md), and [docs/index.html](docs/index.html). -2. Search existing [Issues](https://github.com/CivicSuite/civiccore/issues?q=is%3Aissue) and [Discussions](https://github.com/CivicSuite/civiccore/discussions) for the same topic. +2. Search existing [Issues](https://github.com/townlight/core/issues?q=is%3Aissue) and [Discussions](https://github.com/townlight/core/discussions) for the same topic. 3. Confirm you are on the latest release (see [CHANGELOG](CHANGELOG.md)). ## Audience-specific guidance -- **Module developers / IT integrators** consuming civiccore as a library: include the consuming application name, civiccore version, and Python/Postgres versions. -- **Evaluators** considering civiccore for a new module: a Discussions post under General is the right starting point. +- **Module developers / IT integrators** consuming townlight_core as a library: include the consuming application name, townlight_core version, and Python/Postgres versions. +- **Evaluators** considering townlight_core for a new module: a Discussions post under General is the right starting point. ## Response expectations diff --git a/USER-MANUAL.docx b/USER-MANUAL.docx index 0419698..519e938 100644 Binary files a/USER-MANUAL.docx and b/USER-MANUAL.docx differ diff --git a/USER-MANUAL.md b/USER-MANUAL.md index 3b54040..e848ffe 100644 --- a/USER-MANUAL.md +++ b/USER-MANUAL.md @@ -1,63 +1,67 @@ -# CivicCore User Manual +# Townlight Core User Manual Version: v1.2.1 (current downstream productization line) -Repository: https://github.com/CivicSuite/civiccore +Repository: https://github.com/townlight/core License: Apache 2.0 +> Formerly CivicCore / CivicSuite. The CivicSuite org and its repos moved to +> the townlight org on 2026-08-12; this package's import path is now +> `townlight_core` and its distribution name is `townlight-core`. + This manual has three audiences: -1. **Non-technical evaluators** - what CivicCore is and why it matters. +1. **Non-technical evaluators** - what Townlight Core is and why it matters. 2. **IT and module developers** - how to install it and consume the public API. -3. **Architecture reviewers** - what ships today, what is planned, and how the library fits into the CivicSuite stack. +3. **Architecture reviewers** - what ships today, what is planned, and how the library fits into the Townlight stack. --- ## 1. Non-Technical Overview -### What CivicCore Is +### What Townlight Core Is -CivicCore is the shared platform library underneath CivicSuite. It is the common -Python package that CivicSuite modules use for migrations, LLM plumbing, +Townlight Core is the shared platform library underneath Townlight. It is the common +Python package that Townlight modules use for migrations, LLM plumbing, provenance metadata, audit-chain primitives, export manifests, and local city configuration. It is **not** an app a clerk or resident logs into. End users interact with -module applications such as CivicRecords AI or CivicClerk. CivicCore is the +module applications such as CivicRecords AI or CivicClerk. Townlight Core is the shared foundation those applications import. ### What the current development line ships -- `civiccore.migrations` - migration runner, idempotent guards, and the shared +- `townlight_core.migrations` - migration runner, idempotent guards, and the shared schema baseline. -- `civiccore.db` - shared SQLAlchemy declarative `Base`. -- `civiccore.llm` - provider registry, prompt templates, model registry, +- `townlight_core.db` - shared SQLAlchemy declarative `Base`. +- `townlight_core.llm` - provider registry, prompt templates, model registry, context utilities, and structured-output helpers. -- `civiccore.audit` - hash-chained audit primitives for tamper-evident local +- `townlight_core.audit` - hash-chained audit primitives for tamper-evident local event streams plus legacy-compatible persisted audit-log verification helpers. -- `civiccore.provenance` - source, citation, document, and provenance metadata +- `townlight_core.provenance` - source, citation, document, and provenance metadata contracts. -- `civiccore.connectors` - offline import/export manifest schemas, +- `townlight_core.connectors` - offline import/export manifest schemas, local-first import helpers for supported agenda-platform payloads, and storage-neutral live-sync retry/circuit-breaker primitives plus vendor delta request planning and source-list status projection. -- `civiccore.testing` - no-network mock-city proof contracts for supported +- `townlight_core.testing` - no-network mock-city proof contracts for supported agenda vendors, municipal OIDC, and backup-retention/off-host readiness. -- `civiccore.exports` - static export-bundle manifest and checksum helpers. -- `civiccore.city_profile` - local city/deployment configuration models. -- `civiccore.auth` - bearer-token role helpers, staff-key route gates, and +- `townlight_core.exports` - static export-bundle manifest and checksum helpers. +- `townlight_core.city_profile` - local city/deployment configuration models. +- `townlight_core.auth` - bearer-token role helpers, staff-key route gates, and trusted-header config/source-boundary helpers for protected or mixed public/staff FastAPI routes. -- `civiccore.verification` - content-bound browser release-evidence helpers. -- `civiccore.search` - deterministic text normalization, matching, and +- `townlight_core.verification` - content-bound browser release-evidence helpers. +- `townlight_core.search` - deterministic text normalization, matching, and reciprocal-rank-fusion helpers. -- `civiccore.notifications` - notice deadline planning and publication +- `townlight_core.notifications` - notice deadline planning and publication compliance helpers with actionable warning codes. -- `civiccore.onboarding` - storage-neutral onboarding profile field order, +- `townlight_core.onboarding` - storage-neutral onboarding profile field order, answer parsing, completion-state, and next-question helpers. -- `civiccore.scheduling` - storage-neutral cron validation and next-run +- `townlight_core.scheduling` - storage-neutral cron validation and next-run helpers for module background jobs. -- `civiccore.ingest` - shared discovery/fetch contracts, cited-source +- `townlight_core.ingest` - shared discovery/fetch contracts, cited-source validation helpers, and document ingestion for PDF, DOCX, XLSX, CSV, EML, HTML, and text files with sentence-aware chunking, local Ollama embeddings, and pgvector-backed `documents` / `document_chunks` storage. @@ -65,22 +69,22 @@ shared foundation those applications import. ### What the current development line does not ship yet The following namespaces remain planned extraction targets: -`civiccore.catalog`, `civiccore.exemptions`, and `civiccore.scaffold`. +`townlight_core.catalog`, `townlight_core.exemptions`, and `townlight_core.scaffold`. -`civiccore.onboarding` now ships shared profile interview helpers, but +`townlight_core.onboarding` now ships shared profile interview helpers, but full web onboarding flows and persistence orchestration are still not shipped platform behavior. Credential storage, vendor-specific network adapters, vendor write-back, worker scheduler runtimes, notification delivery queues, and legal determinations are also not shipped platform behaviors. Downstream modules must -not promote those behaviors as shipped CivicCore capability. +not promote those behaviors as shipped Townlight Core capability. ### Why Municipal Teams Should Care - **Sovereignty:** Local-first defaults keep cities in control of their data and infrastructure. -- **Reuse without coupling:** Each CivicSuite module depends on the same +- **Reuse without coupling:** Each Townlight module depends on the same versioned primitives rather than copying logic. - **Auditability:** Shared contracts for provenance, export bundles, and audit chains make compliance evidence more consistent across modules. @@ -91,26 +95,31 @@ not promote those behaviors as shipped CivicCore capability. ### Install from a Release Wheel -CivicCore is distributed as GitHub release artifacts, not PyPI packages: +Townlight Core is distributed as GitHub release artifacts, not PyPI packages: ```bash -pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl +pip install https://github.com/townlight/core/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl ``` +`v1.2.1` predates this rename, so its wheel filename is still +`civiccore-1.2.1-py3-none-any.whl` (a real, already-published artifact). The +next release will ship as `townlight_core--py3-none-any.whl` under +the `townlight-core` distribution name. + Each release publishes `SHA256SUMS.txt` next to the wheel and source distribution. Verify checksums before promoting a release artifact: ```bash curl -L -o SHA256SUMS.txt \ - https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/SHA256SUMS.txt + https://github.com/townlight/core/releases/download/v1.2.1/SHA256SUMS.txt sha256sum -c SHA256SUMS.txt ``` `v1.2.1` is the current published downstream productization line and includes the shared document-ingestion pipeline used by the city-core release train. `v0.22.1` is the first -CivicCore release with a Sigstore-signed -`release-attestation.json` and bundle. Earlier CivicCore releases are retained +Townlight Core release with a Sigstore-signed +`release-attestation.json` and bundle. Earlier Townlight Core releases are retained for historical installs only and must not be treated as provenance baselines unless a future additive attestation is explicitly authorized, published, and recorded in `docs/ops/civiccore-tier1-retrofit-ledger.md`. @@ -118,15 +127,15 @@ recorded in `docs/ops/civiccore-tier1-retrofit-ledger.md`. For local development: ```bash -git clone https://github.com/CivicSuite/civiccore.git -cd civiccore +git clone https://github.com/townlight/core.git +cd core pip install -e .[dev] ``` ### Use LLM Providers ```python -from civiccore.llm import get_provider +from townlight_core.llm import get_provider provider = get_provider("ollama", base_url="http://localhost:11434") text = await provider.generate( @@ -146,7 +155,7 @@ pip install anthropic ### Use Prompt Templates ```python -from civiccore.llm import render_template, resolve_template +from townlight_core.llm import render_template, resolve_template template = await resolve_template( session, @@ -157,12 +166,12 @@ rendered = render_template(template, {"document_text": document_text}) ``` The resolver checks app DB overrides first, code-level overrides second, and -CivicCore defaults third. Missing variables produce actionable render errors. +Townlight Core defaults third. Missing variables produce actionable render errors. ### Use Audit, Provenance, Manifest, Export, and City Profile Primitives ```python -from civiccore import ( +from townlight_core import ( AuditActor, AuditHashChain, AuditSubject, @@ -210,12 +219,12 @@ contract without dictating where records are stored. ### Use Live Connector Sync Primitives -Use `civiccore.connectors` for the shared retry and circuit-breaker state +Use `townlight_core.connectors` for the shared retry and circuit-breaker state machine when a module pulls from a live vendor system. The module still owns its scheduler, tables, credentials, and vendor-specific fetch adapter. ```python -from civiccore.connectors import ( +from townlight_core.connectors import ( SyncCircuitState, SyncRunResult, apply_sync_run_result, @@ -244,11 +253,11 @@ copy, and next scheduled run. ### Run Migrations from a Consumer -CivicCore migrations run before a downstream module's migrations. Consumer -modules use CivicCore's migration runner and keep their own version table so +Townlight Core migrations run before a downstream module's migrations. Consumer +modules use Townlight Core's migration runner and keep their own version table so revision names do not collide. -The release gate verifies the CivicCore migration chain, including +The release gate verifies the Townlight Core migration chain, including `civiccore_0001_baseline_v1` and `civiccore_0002_llm`. --- @@ -257,12 +266,12 @@ The release gate verifies the CivicCore migration chain, including ### Shipped vs Planned -![CivicCore extraction map](docs/diagrams/civiccore-extraction-map.svg) +![civiccore extraction map](docs/diagrams/civiccore-extraction-map.svg) Shipped implementation in the current development line: ```text -civiccore/ +townlight_core/ audit/ hash-chained audit primitives and persisted audit-log helpers city_profile/ local city/deployment configuration models connectors/ offline manifests, local-first import helpers, live-sync primitives @@ -281,7 +290,7 @@ civiccore/ Still planned namespaces: ```text -civiccore/ +townlight_core/ catalog/ future catalog primitives exemptions/ future 50-state public-records exemption engine notifications/ delivery queues and outbound orchestration remain future work @@ -295,7 +304,7 @@ civiccore/ ![Migration order](docs/diagrams/migration-order.svg) -Consumer applications run CivicCore migrations first, then their own module +Consumer applications run Townlight Core migrations first, then their own module migrations. Separate Alembic version tables prevent revision-name collisions. ### LLM Provider Abstraction @@ -309,18 +318,18 @@ them. ### Compatibility Current v0.1.0 module foundations still pin older civiccore lines. -Production-depth consumers should move only to the released CivicCore version +Production-depth consumers should move only to the released Townlight Core version recorded in their compatibility matrix. The suite-wide matrix lives at: -https://github.com/CivicSuite/civicsuite/tree/main/docs/compatibility +https://github.com/townlight/townlight/tree/main/docs/compatibility --- ## Appendix: Where to File Issues -- CivicCore bug: https://github.com/CivicSuite/civiccore/issues -- Suite-wide design issue: https://github.com/CivicSuite/civicsuite/issues +- Townlight Core bug: https://github.com/townlight/core/issues +- Suite-wide design issue: https://github.com/townlight/townlight/issues - Security issue: follow `SECURITY.md`; do not file publicly. The decision tree in `CONTRIBUTING.md` has the full routing rules. diff --git a/USER-MANUAL.pdf b/USER-MANUAL.pdf index 9df3b5f..85809e3 100644 Binary files a/USER-MANUAL.pdf and b/USER-MANUAL.pdf differ diff --git a/USER-MANUAL.txt b/USER-MANUAL.txt index 4f6506d..ec14437 100644 --- a/USER-MANUAL.txt +++ b/USER-MANUAL.txt @@ -1,10 +1,14 @@ -CivicCore User Manual -===================== +Townlight Core User Manual +=========================== Version: v1.2.1 (current downstream productization line) -Repository: https://github.com/CivicSuite/civiccore +Repository: https://github.com/townlight/core License: Apache 2.0 +Formerly CivicCore / CivicSuite. The CivicSuite org and its repos moved to +the townlight org on 2026-08-12; this package's import path is now +townlight_core and its distribution name is townlight-core. + Audience -------- @@ -14,46 +18,46 @@ architecture reviewers. Non-Technical Overview ---------------------- -CivicCore is the shared platform library underneath CivicSuite. It is not an app +Townlight Core is the shared platform library underneath Townlight. It is not an app a clerk or resident logs into. End users interact with module applications such -as CivicRecords AI or CivicClerk. CivicCore is the shared foundation those +as CivicRecords AI or CivicClerk. Townlight Core is the shared foundation those applications import. What the current development line ships: - - civiccore.migrations - migration runner, idempotent guards, and shared + - townlight_core.migrations - migration runner, idempotent guards, and shared schema baseline. - - civiccore.db - shared SQLAlchemy declarative Base. - - civiccore.llm - provider registry, prompt templates, model registry, + - townlight_core.db - shared SQLAlchemy declarative Base. + - townlight_core.llm - provider registry, prompt templates, model registry, context utilities, and structured-output helpers. - - civiccore.audit - hash-chained audit primitives plus persisted audit-log + - townlight_core.audit - hash-chained audit primitives plus persisted audit-log hash and verification helpers. - - civiccore.provenance - source/provenance metadata contracts. - - civiccore.connectors - offline import/export manifest schemas, + - townlight_core.provenance - source/provenance metadata contracts. + - townlight_core.connectors - offline import/export manifest schemas, local-first import helpers for supported agenda-platform payloads, storage-neutral live-sync retry/circuit-breaker primitives, and source-list status projections. - - civiccore.exports - static export-bundle manifest and checksum helpers. - - civiccore.city_profile - local city/deployment configuration models. - - civiccore.auth - bearer-token role helpers for protected or mixed + - townlight_core.exports - static export-bundle manifest and checksum helpers. + - townlight_core.city_profile - local city/deployment configuration models. + - townlight_core.auth - bearer-token role helpers for protected or mixed public/staff FastAPI routes. - - civiccore.verification - content-bound browser release-evidence helpers. - - civiccore.search - deterministic text normalization, matching, and + - townlight_core.verification - content-bound browser release-evidence helpers. + - townlight_core.search - deterministic text normalization, matching, and reciprocal-rank-fusion helpers. - - civiccore.notifications - notice deadline planning and publication + - townlight_core.notifications - notice deadline planning and publication compliance helpers with actionable warning codes. - - civiccore.onboarding - storage-neutral onboarding profile field order, + - townlight_core.onboarding - storage-neutral onboarding profile field order, answer parsing, completion-state, and next-question helpers. - - civiccore.scheduling - storage-neutral cron validation and next-run + - townlight_core.scheduling - storage-neutral cron validation and next-run helpers for module background jobs. Not shipped yet: - civiccore.catalog, civiccore.exemptions, civiccore.scaffold, + townlight_core.catalog, townlight_core.exemptions, townlight_core.scaffold, credential storage, vendor-specific network adapters, vendor write-back, document ingestion, search indexing, scheduler runtimes, notification delivery queues, and legal determinations. - civiccore.ingest ships reusable discovery/fetch contracts and cited-source + townlight_core.ingest ships reusable discovery/fetch contracts and cited-source validation helpers, but not a full document ingestion pipeline. - civiccore.onboarding web UI/persistence flows are also still not shipped. + townlight_core.onboarding web UI/persistence flows are also still not shipped. Why it matters: @@ -66,31 +70,36 @@ Technical Guide Install from the GitHub release wheel: - pip install https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl + pip install https://github.com/townlight/core/releases/download/v1.2.1/civiccore-1.2.1-py3-none-any.whl + + (v1.2.1 predates this rename, so its wheel filename is still + civiccore-1.2.1-py3-none-any.whl -- a real, already-published artifact. + The next release will ship as townlight_core--py3-none-any.whl + under the townlight-core distribution name.) Verify the release artifact: curl -L -o SHA256SUMS.txt \ - https://github.com/CivicSuite/civiccore/releases/download/v1.2.1/SHA256SUMS.txt + https://github.com/townlight/core/releases/download/v1.2.1/SHA256SUMS.txt sha256sum -c SHA256SUMS.txt v1.2.1 is the current published downstream productization line and includes the shared document-ingestion pipeline used by the city-core release train. v0.22.1 is the first -CivicCore release with a Sigstore-signed release-attestation.json and bundle. Earlier CivicCore releases are retained +Townlight Core release with a Sigstore-signed release-attestation.json and bundle. Earlier Townlight Core releases are retained for historical installs only and must not be treated as provenance baselines unless a future additive attestation is explicitly authorized, published, and recorded in docs/ops/civiccore-tier1-retrofit-ledger.md. For local development: - git clone https://github.com/CivicSuite/civiccore.git - cd civiccore + git clone https://github.com/townlight/core.git + cd core pip install -e .[dev] LLM provider example: - from civiccore.llm import get_provider + from townlight_core.llm import get_provider provider = get_provider("ollama", base_url="http://localhost:11434") text = await provider.generate( @@ -100,7 +109,7 @@ LLM provider example: Audit/provenance/export example: - from civiccore import ( + from townlight_core import ( AuditActor, AuditHashChain, AuditSubject, PersistedAuditLogEntry, compute_persisted_audit_hash, verify_persisted_audit_chain, ) @@ -149,22 +158,22 @@ Still planned namespaces: catalog, exemptions, ingest, scaffold, verification -Consumer applications run CivicCore migrations first, then their own module +Consumer applications run Townlight Core migrations first, then their own module migrations. Separate Alembic version tables prevent revision-name collisions. Compatibility ------------- Current v0.1.0 module foundations still pin older civiccore lines. -Production-depth consumers should move only to the released CivicCore version +Production-depth consumers should move only to the released Townlight Core version recorded in their compatibility matrix. Compatibility matrix: -https://github.com/CivicSuite/civicsuite/tree/main/docs/compatibility +https://github.com/townlight/townlight/tree/main/docs/compatibility Issue Routing ------------- - - CivicCore bug: https://github.com/CivicSuite/civiccore/issues - - Suite-wide design issue: https://github.com/CivicSuite/civicsuite/issues + - Townlight Core bug: https://github.com/townlight/core/issues + - Suite-wide design issue: https://github.com/townlight/townlight/issues - Security issue: follow SECURITY.md; do not file publicly. diff --git a/civiccore/migrations/__init__.py b/civiccore/migrations/__init__.py deleted file mode 100644 index 73fc7aa..0000000 --- a/civiccore/migrations/__init__.py +++ /dev/null @@ -1 +0,0 @@ -"""CivicCore: Alembic migrations for shared tables. Run by every consuming module's migration runner BEFORE that module's own migrations. See env.py for the migration-ordering contract from CivicCore Extraction Spec section 14.""" diff --git a/civiccore/models/__init__.py b/civiccore/models/__init__.py deleted file mode 100644 index f960306..0000000 --- a/civiccore/models/__init__.py +++ /dev/null @@ -1,13 +0,0 @@ -"""CivicCore shared SQLAlchemy ORM model exports.""" - -from civiccore.ingest.models import DataSource, Document, DocumentChunk, IngestionStatus, SourceType -from civiccore.platform.task_queue import LocalTask - -__all__ = [ - "DataSource", - "Document", - "DocumentChunk", - "IngestionStatus", - "LocalTask", - "SourceType", -] diff --git a/civiccore/tasks/__init__.py b/civiccore/tasks/__init__.py deleted file mode 100644 index 547de9a..0000000 --- a/civiccore/tasks/__init__.py +++ /dev/null @@ -1,7 +0,0 @@ -"""Local task worker entry points for CivicCore.""" - -from __future__ import annotations - -from civiccore.tasks.registry import get_task_handlers, register_task_handler - -__all__ = ["get_task_handlers", "register_task_handler"] diff --git a/cleanroom/civiccore.Dockerfile b/cleanroom/townlight_core.Dockerfile similarity index 57% rename from cleanroom/civiccore.Dockerfile rename to cleanroom/townlight_core.Dockerfile index 43f9048..f5f1c74 100644 --- a/cleanroom/civiccore.Dockerfile +++ b/cleanroom/townlight_core.Dockerfile @@ -2,17 +2,17 @@ FROM --platform=linux/amd64 python:3.13-slim-bookworm@sha256:bb73517d48bd32016e15eade0c009b2724ec3a025a9975b5cd9b251d0dcadb33 -ARG CIVICCORE_REPO_URL=https://github.com/CivicSuite/civiccore.git -ARG CIVICCORE_COMMIT +ARG TOWNLIGHT_CORE_REPO_URL=https://github.com/townlight/core.git +ARG TOWNLIGHT_CORE_COMMIT ARG COSIGN_VERSION=v3.0.6 ARG COSIGN_SHA256=c956e5dfcac53d52bcf058360d579472f0c1d2d9b69f55209e256fe7783f4c74 -LABEL org.opencontainers.image.title="CivicCore CO-6 cleanroom harness" -LABEL org.opencontainers.image.description="Pinned cleanroom image for CivicCore release and provenance verification." +LABEL org.opencontainers.image.title="Townlight Core CO-6 cleanroom harness" +LABEL org.opencontainers.image.description="Pinned cleanroom image for Townlight Core release and provenance verification." SHELL ["/bin/bash", "-o", "pipefail", "-c"] -RUN test -n "${CIVICCORE_COMMIT}" +RUN test -n "${TOWNLIGHT_CORE_COMMIT}" RUN apt-get update \ && apt-get install -y --no-install-recommends \ @@ -33,26 +33,26 @@ RUN curl -fsSL \ && chmod 0755 /usr/local/bin/cosign \ && cosign version -RUN git clone --filter=blob:none "${CIVICCORE_REPO_URL}" /workspace/civiccore \ - && cd /workspace/civiccore \ - && git fetch --depth 1 origin "${CIVICCORE_COMMIT}" \ - && git checkout --detach "${CIVICCORE_COMMIT}" \ - && test "$(git rev-parse HEAD)" = "${CIVICCORE_COMMIT}" +RUN git clone --filter=blob:none "${TOWNLIGHT_CORE_REPO_URL}" /workspace/townlight-core \ + && cd /workspace/townlight-core \ + && git fetch --depth 1 origin "${TOWNLIGHT_CORE_COMMIT}" \ + && git checkout --detach "${TOWNLIGHT_CORE_COMMIT}" \ + && test "$(git rev-parse HEAD)" = "${TOWNLIGHT_CORE_COMMIT}" -WORKDIR /workspace/civiccore +WORKDIR /workspace/townlight-core RUN python -m pip install --upgrade pip \ && python -m pip install -e .[dev] -COPY scripts/cleanroom/civiccore-cleanroom-runner.sh /usr/local/bin/civiccore-cleanroom-runner -RUN chmod 0755 /usr/local/bin/civiccore-cleanroom-runner +COPY scripts/cleanroom/townlight-core-cleanroom-runner.sh /usr/local/bin/townlight-core-cleanroom-runner +RUN chmod 0755 /usr/local/bin/townlight-core-cleanroom-runner -ENV CIVICCORE_REPO_URL="${CIVICCORE_REPO_URL}" -ENV CIVICCORE_COMMIT="${CIVICCORE_COMMIT}" +ENV TOWNLIGHT_CORE_REPO_URL="${TOWNLIGHT_CORE_REPO_URL}" +ENV TOWNLIGHT_CORE_COMMIT="${TOWNLIGHT_CORE_COMMIT}" ENV CLEANROOM_BASE_IMAGE="python:3.13-slim-bookworm" ENV CLEANROOM_BASE_IMAGE_DIGEST="sha256:bb73517d48bd32016e15eade0c009b2724ec3a025a9975b5cd9b251d0dcadb33" ENV CLEANROOM_COSIGN_VERSION="${COSIGN_VERSION}" ENV CLEANROOM_COSIGN_SHA256="${COSIGN_SHA256}" -ENTRYPOINT ["civiccore-cleanroom-runner"] +ENTRYPOINT ["townlight-core-cleanroom-runner"] CMD ["online"] diff --git a/docs/diagrams/migration-order.mmd b/docs/diagrams/migration-order.mmd index 8f6b951..034bf12 100644 --- a/docs/diagrams/migration-order.mmd +++ b/docs/diagrams/migration-order.mmd @@ -1,7 +1,7 @@ sequenceDiagram autonumber participant Consumer as Consumer app
(records-ai env.py) - participant Civic as civiccore.migrations
.runner.upgrade_to_head + participant Civic as townlight_core.migrations
.runner.upgrade_to_head participant CivicVer as alembic_version_civiccore participant ConsumerVer as alembic_version Consumer->>Civic: upgrade_to_head() [subprocess] @@ -12,4 +12,4 @@ sequenceDiagram Civic-->>Consumer: done Consumer->>Consumer: run consumer-side alembic chain Consumer->>ConsumerVer: stamp '020_phase2_consumer_app_backfill' - Note over CivicVer,ConsumerVer: Two separate version tables
prevent revision-name collisions
between civiccore and consumers. + Note over CivicVer,ConsumerVer: Two separate version tables
prevent revision-name collisions
between townlight_core and consumers. diff --git a/docs/diagrams/migration-order.svg b/docs/diagrams/migration-order.svg index b0be701..dae24ac 100644 --- a/docs/diagrams/migration-order.svg +++ b/docs/diagrams/migration-order.svg @@ -1 +1 @@ -alembic_versionalembic_version_civiccoreciviccore.migrations.runner.upgrade_to_headConsumer app(records-ai env.py)alembic_versionalembic_version_civiccoreciviccore.migrations.runner.upgrade_to_headConsumer app(records-ai env.py)Two separate version tablesprevent revision-name collisionsbetween civiccore and consumers.upgrade_to_head() [subprocess]1civiccore_0001_baseline_v12civiccore_0002_llm (ALTER prompt_templates)3civiccore_0003_local_task_queue4stamp 'civiccore_0003_local_task_queue'5done6run consumer-side alembic chain7stamp '020_phase2_consumer_app_backfill'8 \ No newline at end of file +alembic_versionalembic_version_civiccoretownlight_core.migrations.runner.upgrade_to_headConsumer app(records-ai env.py)alembic_versionalembic_version_civiccoretownlight_core.migrations.runner.upgrade_to_headConsumer app(records-ai env.py)Two separate version tablesprevent revision-name collisionsbetween townlight_core and consumers.upgrade_to_head() [subprocess]1civiccore_0001_baseline_v12civiccore_0002_llm (ALTER prompt_templates)3civiccore_0003_local_task_queue4stamp 'civiccore_0003_local_task_queue'5done6run consumer-side alembic chain7stamp '020_phase2_consumer_app_backfill'8 \ No newline at end of file diff --git a/docs/diagrams/provider-abstraction.mmd b/docs/diagrams/provider-abstraction.mmd index a985406..a89b34e 100644 --- a/docs/diagrams/provider-abstraction.mmd +++ b/docs/diagrams/provider-abstraction.mmd @@ -1,6 +1,6 @@ graph LR Caller["Consumer code
(records-ai, future modules)"] - subgraph PROVIDERS["civiccore.llm.providers"] + subgraph PROVIDERS["townlight_core.llm.providers"] ABC["LLMProvider ABC
generate / embed /
embed_batch / name /
supports_images"] Reg["PROVIDER_REGISTRY
+ register_provider"] Factory["build_provider(name, config)"] diff --git a/docs/diagrams/provider-abstraction.svg b/docs/diagrams/provider-abstraction.svg index a8fae3a..f536ff3 100644 --- a/docs/diagrams/provider-abstraction.svg +++ b/docs/diagrams/provider-abstraction.svg @@ -1 +1 @@ -

civiccore.llm.providers

implements

implements

implements

implements

Consumer code
(records-ai, future modules)

LLMProvider ABC
generate / embed /
embed_batch / name /
supports_images

PROVIDER_REGISTRY
+ register_provider

build_provider(name, config)

OllamaConfig

OpenAIConfig

AnthropicConfig

OllamaProvider
local /api/generate

OpenAIProvider
cloud, optional extra

AnthropicProvider
cloud, optional extra

Third-party
@register_provider('custom')

 \ No newline at end of file +

townlight_core.llm.providers

implements

implements

implements

implements

Consumer code
(records-ai, future modules)

LLMProvider ABC
generate / embed /
embed_batch / name /
supports_images

PROVIDER_REGISTRY
+ register_provider

build_provider(name, config)

OllamaConfig

OpenAIConfig

AnthropicConfig

OllamaProvider
local /api/generate

OpenAIProvider
cloud, optional extra

AnthropicProvider
cloud, optional extra

Third-party
@register_provider('custom')

 \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 8040dd2..3dd566f 100644 --- a/docs/index.html +++ b/docs/index.html @@ -3,8 +3,8 @@ - -CivicCore v1.2.1 - CivicSuite shared platform library + +Townlight Core v1.2.1 - Townlight shared platform library