pf-core 0.1.0__tar.gz

pf_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mike Farr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pf_core-0.1.0/PKG-INFO

@@ -0,0 +1,152 @@
+Metadata-Version: 2.4
+Name: pf-core
+Version: 0.1.0
+Summary: Dependency-light Python foundation (logging, exceptions, config, utils) with LLM clients, anti-slop guards, cost tracking, and an opinionated FastAPI+SQLAlchemy framework available as opt-in extras
+Author: Mike Farr
+License-Expression: MIT
+Project-URL: Repository, https://github.com/phierceweb/pf-core
+Project-URL: Changelog, https://github.com/phierceweb/pf-core/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/phierceweb/pf-core/issues
+Keywords: llm,openrouter,anthropic,fastapi,sqlalchemy,framework,cost-tracking,eval,structured-logging
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: structlog>=24.0
+Requires-Dist: nanoid>=2.0
+Requires-Dist: rich>=13.7
+Provides-Extra: http
+Requires-Dist: httpx>=0.27; extra == "http"
+Provides-Extra: cli
+Requires-Dist: typer>=0.12; extra == "cli"
+Requires-Dist: click>=8.0; extra == "cli"
+Provides-Extra: validate
+Requires-Dist: json-repair>=0.40; extra == "validate"
+Requires-Dist: pydantic>=2.0; extra == "validate"
+Provides-Extra: llm
+Requires-Dist: pf-core[http,validate]; extra == "llm"
+Requires-Dist: tenacity>=8.0; extra == "llm"
+Provides-Extra: db
+Requires-Dist: sqlalchemy>=2.0; extra == "db"
+Requires-Dist: alembic>=1.13; extra == "db"
+Provides-Extra: web
+Requires-Dist: fastapi>=0.115; extra == "web"
+Requires-Dist: jinja2>=3.1; extra == "web"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "web"
+Provides-Extra: jobs
+Requires-Dist: pf-core[cli,db]; extra == "jobs"
+Requires-Dist: pydantic>=2.0; extra == "jobs"
+Provides-Extra: tracking
+Requires-Dist: pf-core[db,llm]; extra == "tracking"
+Provides-Extra: admin
+Requires-Dist: pf-core[tracking,web]; extra == "admin"
+Provides-Extra: eval
+Requires-Dist: pf-core[jobs,tracking]; extra == "eval"
+Provides-Extra: mysql
+Requires-Dist: pymysql>=1.1; extra == "mysql"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3.2; extra == "postgres"
+Provides-Extra: redis
+Requires-Dist: dogpile.cache>=1.3; extra == "redis"
+Requires-Dist: redis>=5.0; extra == "redis"
+Provides-Extra: ratelimit
+Requires-Dist: pf-core[web]; extra == "ratelimit"
+Requires-Dist: slowapi>=0.1.9; extra == "ratelimit"
+Provides-Extra: jsonschema
+Requires-Dist: jsonschema>=4.0; extra == "jsonschema"
+Provides-Extra: articles
+Requires-Dist: trafilatura>=1.6; extra == "articles"
+Requires-Dist: htmldate>=1.7; extra == "articles"
+Requires-Dist: tenacity>=8.0; extra == "articles"
+Provides-Extra: crawl
+Requires-Dist: pf-core[articles,http]; extra == "crawl"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == "anthropic"
+Provides-Extra: image-phash
+Requires-Dist: ImageHash>=4.3; extra == "image-phash"
+Requires-Dist: Pillow>=10.0; extra == "image-phash"
+Provides-Extra: full
+Requires-Dist: pf-core[db]; extra == "full"
+Requires-Dist: pf-core[web]; extra == "full"
+Requires-Dist: pf-core[llm]; extra == "full"
+Requires-Dist: pf-core[cli]; extra == "full"
+Requires-Dist: pf-core[jobs]; extra == "full"
+Requires-Dist: pf-core[tracking]; extra == "full"
+Requires-Dist: pf-core[admin]; extra == "full"
+Requires-Dist: pf-core[eval]; extra == "full"
+Requires-Dist: pf-core[redis]; extra == "full"
+Requires-Dist: pf-core[ratelimit]; extra == "full"
+Requires-Dist: pf-core[jsonschema]; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: factory-boy>=3.3; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Provides-Extra: test-containers
+Requires-Dist: testcontainers[mysql]>=4.0; extra == "test-containers"
+Dynamic: license-file
+
+# pf-core
+
+A dependency-light Python foundation for building LLM applications — and one built to be worked on by AI coding agents as much as by people. The base install provides structured logging, an exception hierarchy, config-from-env, and a service/repo architecture; opt-in extras add LLM clients, output validation, cost tracking and budgets, an eval harness, and a FastAPI + SQLAlchemy app framework. Capabilities compose orthogonally — the foundation alone, the LLM layer without a database, or the web layer without LLMs.
+
+## Built for AI-assisted development
+
+The conventions that keep a codebase legible to an AI agent are enforced, not suggested. A build gate fails CI when a file grows past its line budget — small files stay within a model's working context and edit cleanly — and a companion checker flags imports that cross the layered architecture the wrong way. Logging, errors, config, and data access each have one obvious way to do them, documented one-module-per-file for retrieval, so generated code lands in the same shapes as hand-written code instead of drifting. The result is a substrate where an agent can do real work and the guardrails hold.
+
+## One interface over every LLM backend — including Claude Code
+
+OpenRouter (paid API), the Anthropic SDK, and Claude Code (a local Claude Max session, $0 per call) sit behind the same `chat(messages, model) -> (content, usage)` interface. A YAML model router assigns a backend per agent and falls back to the next available one; a registry accepts custom backends (Ollama, direct OpenAI, …). Because the clients are interchangeable and `pf_core.parallel` fans work across a thread pool, a batch of LLM calls can run concurrently and route anywhere — a large batch pushed onto a Claude Max subscription instead of spending API credits, or spread across providers — while every call is still tracked and budget-checked the same way.
+
+## Output guards and observability
+
+LLMs return fenced, truncated, or not-quite-JSON output; pf-core recovers it (`pf_core.llm.parse`) and validates the result against a schema with optional semantic and cross-field checks (`pf_core.llm.validate`) — available without the client stack, so output from any transport can be guarded. Every call can record one database row (prompt, tokens, cost, validations, and the job it belongs to), making spend and quality queryable and runs replayable. Pre-call budget checks enforce daily/monthly caps with a kill-switch, a cache skips paying for identical calls, prompts are versioned and linked to the runs they produced, and an eval harness replays golden sets against a new model or prompt to show whether a change is an improvement before it ships.
+
+## The rest of the framework
+
+A multi-dialect database layer (SQLite / MySQL / PostgreSQL, identical API) with a shared Alembic runner; a FastAPI app factory with self-contained error pages and content negotiation; a job tracker with a state machine, idempotent step history, and worker leases so multi-step work survives restarts; a mountable admin dashboard for runs, costs, and budgets; and pipeline helpers for run-records, baselines, and stage-cascade cache invalidation. See **[docs/modules.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/modules.md)** for the full index.
+
+## Install
+
+```bash
+pip install pf-core                  # foundation only — no LLM, no DB, no web
+pip install pf-core[validate]        # + output guards (no clients/HTTP)
+pip install pf-core[llm]             # + LLM clients (includes [validate])
+pip install pf-core[full,postgres]   # the whole app framework
+```
+
+Until the first PyPI release, install from a tagged commit:
+
+```bash
+pip install "pf-core[llm] @ git+https://github.com/phierceweb/pf-core.git@v0.1.0"
+```
+
+Pinning to a **tagged release** is recommended for stability — `main` is the development line and may contain unreleased work between tags. Extras compose orthogonally (`[db]` without LLM, `[web]` without `[db]`, `[llm]` standalone); importing a gated module without its extra raises an `ImportError` naming the extra and the pip command. Full matrix and release/update flow: **[docs/INSTALLATION.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/INSTALLATION.md)**.
+
+## Documentation
+
+- **[docs/INSTALLATION.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/INSTALLATION.md)** — extras matrix, install/release/update flows, verification
+- **[docs/modules.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/modules.md)** — one-line-per-module index, grouped by concern
+- **[docs/](https://github.com/phierceweb/pf-core/tree/main/src/pf_core/docs)** — per-module reference with usage and parameter detail
+- **[CHANGELOG.md](https://github.com/phierceweb/pf-core/blob/main/CHANGELOG.md)** — release history
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[full,articles,anthropic,image-phash,dev]"   # everything, so the full suite runs
+pre-commit install
+pytest
+python bin/verify-bare-install                                # confirm the base install stays dependency-light
+```
+
+Pytest fixtures auto-register as a plugin via the `pf_core` entry point — no `conftest.py` import needed in consumers. Contribution guidelines: **[CONTRIBUTING.md](https://github.com/phierceweb/pf-core/blob/main/CONTRIBUTING.md)**.

pf_core-0.1.0/README.md

@@ -0,0 +1,55 @@
+# pf-core
+
+A dependency-light Python foundation for building LLM applications — and one built to be worked on by AI coding agents as much as by people. The base install provides structured logging, an exception hierarchy, config-from-env, and a service/repo architecture; opt-in extras add LLM clients, output validation, cost tracking and budgets, an eval harness, and a FastAPI + SQLAlchemy app framework. Capabilities compose orthogonally — the foundation alone, the LLM layer without a database, or the web layer without LLMs.
+
+## Built for AI-assisted development
+
+The conventions that keep a codebase legible to an AI agent are enforced, not suggested. A build gate fails CI when a file grows past its line budget — small files stay within a model's working context and edit cleanly — and a companion checker flags imports that cross the layered architecture the wrong way. Logging, errors, config, and data access each have one obvious way to do them, documented one-module-per-file for retrieval, so generated code lands in the same shapes as hand-written code instead of drifting. The result is a substrate where an agent can do real work and the guardrails hold.
+
+## One interface over every LLM backend — including Claude Code
+
+OpenRouter (paid API), the Anthropic SDK, and Claude Code (a local Claude Max session, $0 per call) sit behind the same `chat(messages, model) -> (content, usage)` interface. A YAML model router assigns a backend per agent and falls back to the next available one; a registry accepts custom backends (Ollama, direct OpenAI, …). Because the clients are interchangeable and `pf_core.parallel` fans work across a thread pool, a batch of LLM calls can run concurrently and route anywhere — a large batch pushed onto a Claude Max subscription instead of spending API credits, or spread across providers — while every call is still tracked and budget-checked the same way.
+
+## Output guards and observability
+
+LLMs return fenced, truncated, or not-quite-JSON output; pf-core recovers it (`pf_core.llm.parse`) and validates the result against a schema with optional semantic and cross-field checks (`pf_core.llm.validate`) — available without the client stack, so output from any transport can be guarded. Every call can record one database row (prompt, tokens, cost, validations, and the job it belongs to), making spend and quality queryable and runs replayable. Pre-call budget checks enforce daily/monthly caps with a kill-switch, a cache skips paying for identical calls, prompts are versioned and linked to the runs they produced, and an eval harness replays golden sets against a new model or prompt to show whether a change is an improvement before it ships.
+
+## The rest of the framework
+
+A multi-dialect database layer (SQLite / MySQL / PostgreSQL, identical API) with a shared Alembic runner; a FastAPI app factory with self-contained error pages and content negotiation; a job tracker with a state machine, idempotent step history, and worker leases so multi-step work survives restarts; a mountable admin dashboard for runs, costs, and budgets; and pipeline helpers for run-records, baselines, and stage-cascade cache invalidation. See **[docs/modules.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/modules.md)** for the full index.
+
+## Install
+
+```bash
+pip install pf-core                  # foundation only — no LLM, no DB, no web
+pip install pf-core[validate]        # + output guards (no clients/HTTP)
+pip install pf-core[llm]             # + LLM clients (includes [validate])
+pip install pf-core[full,postgres]   # the whole app framework
+```
+
+Until the first PyPI release, install from a tagged commit:
+
+```bash
+pip install "pf-core[llm] @ git+https://github.com/phierceweb/pf-core.git@v0.1.0"
+```
+
+Pinning to a **tagged release** is recommended for stability — `main` is the development line and may contain unreleased work between tags. Extras compose orthogonally (`[db]` without LLM, `[web]` without `[db]`, `[llm]` standalone); importing a gated module without its extra raises an `ImportError` naming the extra and the pip command. Full matrix and release/update flow: **[docs/INSTALLATION.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/INSTALLATION.md)**.
+
+## Documentation
+
+- **[docs/INSTALLATION.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/INSTALLATION.md)** — extras matrix, install/release/update flows, verification
+- **[docs/modules.md](https://github.com/phierceweb/pf-core/blob/main/src/pf_core/docs/modules.md)** — one-line-per-module index, grouped by concern
+- **[docs/](https://github.com/phierceweb/pf-core/tree/main/src/pf_core/docs)** — per-module reference with usage and parameter detail
+- **[CHANGELOG.md](https://github.com/phierceweb/pf-core/blob/main/CHANGELOG.md)** — release history
+
+## Development
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[full,articles,anthropic,image-phash,dev]"   # everything, so the full suite runs
+pre-commit install
+pytest
+python bin/verify-bare-install                                # confirm the base install stays dependency-light
+```
+
+Pytest fixtures auto-register as a plugin via the `pf_core` entry point — no `conftest.py` import needed in consumers. Contribution guidelines: **[CONTRIBUTING.md](https://github.com/phierceweb/pf-core/blob/main/CONTRIBUTING.md)**.

pf_core-0.1.0/pyproject.toml

@@ -0,0 +1,273 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pf-core"
+version = "0.1.0"
+description = "Dependency-light Python foundation (logging, exceptions, config, utils) with LLM clients, anti-slop guards, cost tracking, and an opinionated FastAPI+SQLAlchemy framework available as opt-in extras"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Mike Farr" }]
+keywords = [
+    "llm",
+    "openrouter",
+    "anthropic",
+    "fastapi",
+    "sqlalchemy",
+    "framework",
+    "cost-tracking",
+    "eval",
+    "structured-logging",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    # Foundation kernel: the dependency-light architectural base — structured
+    # logging, exception hierarchy, config + env resolvers, utils, the
+    # ``Service`` base class, and console output. Everything else (LLM
+    # clients + anti-slop guards, HTTP utils, CLI scaffolding, database, web,
+    # jobs, eval) lives behind opt-in extras so a project can adopt pf-core's
+    # discipline without installing the LLM/HTTP stack. See
+    # docs/INSTALLATION.md for the extras matrix.
+    #
+    # These five are the only hard deps: dotenv (config), pyyaml (yaml config,
+    # imported lazily), structlog (logging), nanoid (id generation), rich
+    # (console output in pf_core.output). No httpx, pydantic, json-repair,
+    # tenacity, or typer here — those moved to [http]/[validate]/[llm]/[cli].
+    "python-dotenv>=1.0",
+    "pyyaml>=6.0",
+    "structlog>=24.0",
+    "nanoid>=2.0",
+    "rich>=13.7",
+]
+
+[project.optional-dependencies]
+# ---------------------------------------------------------------------------
+# Capability extras — each unlocks a tier of pf-core's framework surface.
+# Each composes orthogonally on the foundation base: [db] without LLM, [web]
+# without [db], [llm] standalone.
+# ---------------------------------------------------------------------------
+
+# HTTP utils: pf_core.utils.url_liveness / pf_core.utils.urls (URL liveness +
+# Wayback round-timestamp checks). The lightest network tier — just httpx.
+# Pulled in transitively by [llm].
+http = ["httpx>=0.27"]
+
+# CLI scaffolding: pf_core.cli.create_cli. Install this to reuse pf-core's
+# Typer-based command scaffolding in your own CLI; foundation-only projects
+# can equally just depend on typer directly. Pulled in by [jobs].
+cli = [
+    "typer>=0.12",
+    "click>=8.0",
+]
+
+# Anti-slop output guards: pf_core.llm.parse (+ json-repair recovery) and
+# pf_core.llm.validate (pydantic schema/semantic validation). Pure-Python —
+# NO httpx / clients / tenacity / db — so a project can validate LLM output
+# (or wire its own transport) without the client stack. The stdlib/pyyaml
+# members of pf_core.llm (json_helpers, url_check, prompts, router,
+# safe_apply) need no extra at all once pf_core.llm imports lazily.
+validate = [
+    "json-repair>=0.40",
+    "pydantic>=2.0",
+]
+
+# LLM tier: pf_core.clients.* (OpenRouter / Brave / Claude Code) on top of
+# the anti-slop guards. = [validate] + [http] (clients need httpx) + tenacity
+# (retry). [llm] ⊇ [validate], so every existing [llm]/[full]/[tracking]
+# consumer keeps the same dependency closure (mirrors [tracking] = [db,llm]).
+# Note: tracked_call records to the DB, so it additionally needs [tracking]
+# (= [db,llm]); importing it without [db] raises a friendly 'tracking' error.
+llm = [
+    "pf-core[validate,http]",
+    "tenacity>=8.0",
+]
+
+# Database layer: pf_core.db.*, pf_core.alembic, fully-functional cost guards
+# (BudgetRepo / CostRateRepo). Without [db], pf_core.budget.check_budget still
+# imports and short-circuits gracefully; pf_core.db.* and pf_core.alembic
+# raise ImportError. SQLite needs no driver extra (stdlib).
+db = [
+    "sqlalchemy>=2.0",
+    "alembic>=1.13",
+]
+
+# FastAPI web layer: pf_core.web.app_factory, error pages, markdown,
+# pagination, templates.
+web = [
+    "fastapi>=0.115",
+    "jinja2>=3.1",
+    "uvicorn[standard]>=0.30",
+]
+
+# Job tracker: pf_core.jobs.* (state machine, step history, worker leases)
+# and the pf-jobs CLI. Requires [db] for persistence and [cli] for the CLI;
+# pydantic backs job-argument schema validation in pf_core.jobs.registry.
+jobs = ["pf-core[db,cli]", "pydantic>=2.0"]
+
+# DB-backed LLM run tracking: pf_core.llm.tracking.* and pf_core.llm.cache.*
+# (one row per call with prompts, tokens, cost, validations, job
+# attribution). Requires [db] for persistence and [llm] for the parse/retry
+# machinery it records around (tracking code itself uses tenacity).
+tracking = ["pf-core[db,llm]"]
+
+# Admin dashboard sub-app: pf_core.web.llm_admin (runs, costs, jobs, cache
+# stats, budgets). Requires [web,tracking].
+admin = ["pf-core[web,tracking]"]
+
+# Eval harness: pf_core.eval.* (golden-set replay, structured-diff and
+# LLM-judge comparators, pf-eval CLI). Requires [tracking,jobs].
+eval = ["pf-core[tracking,jobs]"]
+
+# ---------------------------------------------------------------------------
+# Database driver extras — pick one per consumer (mutually exclusive).
+# ---------------------------------------------------------------------------
+mysql = ["pymysql>=1.1"]
+postgres = ["psycopg[binary]>=3.2"]
+
+# ---------------------------------------------------------------------------
+# Other capability extras
+# ---------------------------------------------------------------------------
+
+# Redis-backed cache region: pf_core.cache (with graceful no-op fallback
+# when Redis is unreachable).
+redis = ["dogpile.cache>=1.3", "redis>=5.0"]
+
+# Per-IP rate limiting on FastAPI routes. Requires [web].
+ratelimit = [
+    "pf-core[web]",
+    "slowapi>=0.1.9",
+]
+
+# Strict JSON Schema validation in pf_core.llm.validate (stdlib jsonschema
+# rather than the lighter Pydantic path).
+jsonschema = ["jsonschema>=4.0"]
+
+# Article fetch + extract: pf_core.utils.article_fetch (title, body,
+# publish-date with Wayback Machine fallback for paywalled URLs). tenacity
+# drives the Wayback retry loop.
+articles = [
+    "trafilatura>=1.6",
+    "htmldate>=1.7",
+    "tenacity>=8.0",
+]
+
+# Intent-named meta-extra: "I want to crawl/fetch web pages." Composes the
+# fetch+extract stack ([articles]) with the URL-utils tier ([http]) —
+# article_fetch imports pf_core.utils.urls, which needs httpx. Exists so a
+# consumer asking "how do I crawl?" gets one named line instead of having to
+# know the composition. Front-end serving is a different intent: [web].
+crawl = ["pf-core[http,articles]"]
+
+# Direct Anthropic API client (pf_core.clients.anthropic). Provides a
+# multimodal-capable alternative to the OpenRouter and Claude Code
+# transports for consumers that want the official SDK's vision support
+# and direct usage / cache-token reporting.
+anthropic = ["anthropic>=0.30"]
+
+# Perceptual-hash image dedup: pf_core.utils.phash (DCT-based phash via
+# ImageHash + Pillow). Used by document-extraction consumers to detect
+# repeated page decorations (header logos, footer marks) and re-encoded
+# duplicates that sha256 would miss.
+image-phash = [
+    "ImageHash>=4.3",
+    "Pillow>=10.0",
+]
+
+# ---------------------------------------------------------------------------
+# Meta-extra for full-stack apps that want the whole framework.
+# Add the dialect driver ([mysql]/[postgres]) and any optional capability
+# extras ([articles]) separately.
+# ---------------------------------------------------------------------------
+full = [
+    "pf-core[db]",
+    "pf-core[web]",
+    "pf-core[llm]",
+    "pf-core[cli]",
+    "pf-core[jobs]",
+    "pf-core[tracking]",
+    "pf-core[admin]",
+    "pf-core[eval]",
+    "pf-core[redis]",
+    "pf-core[ratelimit]",
+    "pf-core[jsonschema]",
+]
+
+# ---------------------------------------------------------------------------
+# Dev / test extras
+# ---------------------------------------------------------------------------
+dev = [
+    "pytest>=8.0",
+    "httpx>=0.27",
+    "factory-boy>=3.3",
+    "ruff>=0.6",
+    "pre-commit>=3.5",
+]
+test-containers = [
+    "testcontainers[mysql]>=4.0",
+]
+
+[project.urls]
+Repository = "https://github.com/phierceweb/pf-core"
+Changelog = "https://github.com/phierceweb/pf-core/blob/main/CHANGELOG.md"
+Issues = "https://github.com/phierceweb/pf-core/issues"
+
+[project.scripts]
+pf-guards = "pf_core.guards.structure:run_cli"
+
+[project.entry-points.pytest11]
+pf_core = "pf_core.testing.fixtures"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+"pf_core" = ["docs/*.md", "py.typed"]
+"pf_core.web.llm_admin" = ["templates/*.html"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]   # don't collect templates/consumer-*/tests/ (they hold __PKG__ tokens)
+pythonpath = ["."]
+
+# ---------------------------------------------------------------------------
+# Lint config — ruff
+# ---------------------------------------------------------------------------
+# Conservative starting set: what ruff catches by default (E, W, F) plus
+# bugbear (B) for common bug/antipattern checks. isort (I) and pyupgrade
+# (UP) are deferred to a separate formatting pass to keep enforcement
+# diffs reviewable. Line length (E501) is also deferred — most existing
+# code is within 100, but enforcing E501 would force a layout pass we
+# haven't decided on yet.
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes (unused imports, undefined names, etc.)
+    "B",   # flake8-bugbear (common bugs / antipatterns)
+]
+ignore = [
+    "E501",  # line too long — defer to a separate formatting pass
+    "B008",  # function call in default arg — common in FastAPI / Typer
+    "B904",  # raise-from — `raise X from y` discipline pre-dates this lint
+]
+
+[tool.ruff.lint.per-file-ignores]
+# Test files are allowed to use bare asserts and unused-but-imported
+# fixtures; F841 (unused local) often shows up when a test imports a
+# class only to verify it's importable. Keep these lints active in
+# `src/` where they actually catch bugs.
+"tests/**/*.py" = ["B011"]

pf_core-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pf_core-0.1.0/src/pf_core/__init__.py

@@ -0,0 +1,20 @@
+"""pf-core: a dependency-light Python foundation.
+
+The base install (``pip install pf-core``) is the architectural foundation
+only: structured logging, an exception hierarchy, config + env resolvers,
+utils, and the ``Service`` base class — five small deps (structlog,
+python-dotenv, pyyaml, nanoid, rich), no httpx/pydantic/LLM stack.
+
+Everything else ships as opt-in, orthogonally-composable extras: anti-slop
+output guards (``[validate]``), LLM clients (``[llm]`` ⊇ ``[validate]``), HTTP
+utils (``[http]``), CLI scaffolding (``[cli]``), and the FastAPI + SQLAlchemy
+app framework (``[db]``, ``[web]``, ``[jobs]``, ``[tracking]``, ``[eval]``,
+``[admin]``). See ``docs/INSTALLATION.md`` for the extras matrix.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("pf-core")
+except PackageNotFoundError:  # running from a source tree with no install
+    __version__ = "0.0.0+unknown"

pf_core-0.1.0/src/pf_core/_extras.py

@@ -0,0 +1,64 @@
+"""Friendly errors for missing optional-dependency extras.
+
+The foundation install (``pip install pf-core``) is dependency-light: it does
+not ship httpx, pydantic, json-repair, tenacity, or typer. Modules that need
+those live behind opt-in extras ([http], [llm], [cli], [jobs], ...). When such
+a module is imported without its extra installed, the bare third-party
+``ImportError`` ("No module named 'json_repair'") is opaque. This helper turns
+it into a message that names the extra and the exact pip command.
+
+Usage at the top of a gated leaf module::
+
+    try:
+        import httpx
+    except ImportError as e:  # pragma: no cover - exercised by bare-install CI
+        from pf_core._extras import extra_import_error
+
+        raise extra_import_error(
+            "llm", "httpx", feature="pf_core.clients.openrouter"
+        ) from e
+"""
+
+from __future__ import annotations
+
+# Extra name -> the pip target a user should install. Anything not listed
+# falls back to ``pf-core[<extra>]``.
+_INSTALL: dict[str, str] = {
+    "http": "pf-core[http]",
+    "cli": "pf-core[cli]",
+    "validate": "pf-core[validate]",
+    "llm": "pf-core[llm]",
+    "db": "pf-core[db]",
+    "web": "pf-core[web]",
+    "jobs": "pf-core[jobs]",
+    "tracking": "pf-core[tracking]",
+    "eval": "pf-core[eval]",
+    "admin": "pf-core[admin]",
+    "articles": "pf-core[articles]",
+    "jsonschema": "pf-core[jsonschema]",
+    "redis": "pf-core[redis]",
+    "ratelimit": "pf-core[ratelimit]",
+}
+
+
+def install_target(extra: str) -> str:
+    """Return the ``pip install`` target for an extra (e.g. ``pf-core[llm]``)."""
+    return _INSTALL.get(extra, f"pf-core[{extra}]")
+
+
+def extra_import_error(extra: str, package: str, *, feature: str) -> ImportError:
+    """Build an ``ImportError`` that names the missing extra and pip command.
+
+    Args:
+        extra: The optional-dependency extra that ships ``package`` (e.g. ``"llm"``).
+        package: The third-party import name that failed (e.g. ``"json_repair"``).
+        feature: The pf-core module or capability the caller was importing, used
+            in the message (e.g. ``"pf_core.llm.parse"``).
+
+    Returns:
+        An ``ImportError`` to ``raise ... from`` the original failure.
+    """
+    return ImportError(
+        f"{feature} requires the '{extra}' extra; '{package}' is not installed. "
+        f"Install it with:  pip install {install_target(extra)}"
+    )

pf_core-0.1.0/src/pf_core/alembic.py

@@ -0,0 +1,72 @@
+"""
+Alembic migration helper — shared env.py logic for all projects.
+
+Supports SQLite (batch mode), MySQL/MariaDB, and PostgreSQL. Uses pf_core.db
+for engine management so migrations share the same connection config as the app.
+
+Usage in a project's ``alembic/env.py``::
+
+    from pf_core.alembic import run_migrations_online
+
+    run_migrations_online()
+
+With SQLite fallback (e.g., an essay-grading app on SQLite)::
+
+    from pf_core.alembic import run_migrations_online
+
+    run_migrations_online(fallback_sqlite="grading.db")
+
+With explicit metadata (for autogenerate)::
+
+    from myapp.models import Base
+    from pf_core.alembic import run_migrations_online
+
+    run_migrations_online(target_metadata=Base.metadata)
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from alembic import context
+
+from pf_core.db import db_url, get_engine, is_sqlite
+
+
+def run_migrations_online(
+    *,
+    fallback_sqlite: str = "",
+    target_metadata: Any = None,
+    compare_type: bool = False,
+) -> None:
+    """Run Alembic migrations in online mode.
+
+    Call this from your project's ``alembic/env.py``. Handles:
+    - SQLite batch mode (``render_as_batch=True``)
+    - MySQL/MariaDB and PostgreSQL standard mode
+    - Engine reuse via ``pf_core.db.get_engine()``
+
+    Args:
+        fallback_sqlite: Path to SQLite file if DATABASE_URL is not set.
+        target_metadata: SQLAlchemy MetaData for autogenerate support.
+            Pass ``None`` (default) for raw-SQL migrations.
+        compare_type: Whether Alembic should detect column type changes.
+    """
+    if context.is_offline_mode():
+        raise RuntimeError(
+            "Offline mode is not supported. Set DATABASE_URL and run in online mode."
+        )
+
+    url = db_url(fallback_sqlite=fallback_sqlite)
+    sqlite = is_sqlite(url)
+    engine = get_engine(url)
+
+    with engine.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=compare_type,
+            render_as_batch=sqlite,
+        )
+        with context.begin_transaction():
+            context.run_migrations()