jfastframework 0.1.0a1__tar.gz

jfastframework-0.1.0a1/.env.example

@@ -0,0 +1,37 @@
+# Copy to .env and fill in. Never commit .env.
+
+# --- kernel ---
+JFAST_APP_NAME=jfast-service
+JFAST_ENV=local            # local | dev | staging | prod
+JFAST_DEBUG=false          # true leaks exception messages to clients
+JFAST_PORT=8000
+
+# --- edge protections (all off unless set) ---
+# JFAST_READINESS_TIMEOUT=2.0     # seconds one plugin gets to answer /ready
+# JFAST_CORS_ORIGINS=["https://app.example.com"]
+# JFAST_CORS_ALLOW_CREDENTIALS=false
+# JFAST_TRUSTED_HOSTS=["api.example.com"]
+# JFAST_MAX_BODY_BYTES=10485760   # 10 MiB; unset means no limit
+# JFAST_REQUEST_TIMEOUT=30        # seconds before a request is answered 504
+# JFAST_DOCS_URL=/docs            # closed in prod unless set explicitly
+
+# --- observability plugin ---
+JFAST_LOG_LEVEL=INFO
+JFAST_LOG_JSON_LOGS=true
+
+# --- database plugin (extra: jfastframework[db]) ---
+JFAST_DB_DSN=postgresql+asyncpg://app:CHANGEME@localhost:5432/app
+JFAST_DB_POOL_SIZE=10
+POSTGRES_PASSWORD=CHANGEME
+
+# --- cache plugin (extra: jfastframework[cache]) ---
+JFAST_CACHE_URL=redis://localhost:6379/0
+
+# --- sentry plugin (extra: jfastframework[sentry]) ---
+# JFAST_SENTRY_DSN=
+JFAST_SENTRY_TRACES_SAMPLE_RATE=0.1
+
+# --- rag plugin (extra: jfastframework[rag,db]) ---
+JFAST_RAG_DIMENSIONS=768
+JFAST_RAG_OLLAMA_URL=http://localhost:11434
+JFAST_RAG_OLLAMA_MODEL=nomic-embed-text

jfastframework-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,125 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install
+        # setuptools is upgraded first. It is not a dependency of this
+        # package -- hatchling does the building -- but setup-python ships one
+        # in the runner's environment, pip-audit sees it, and the version it
+        # ships has lagged behind published advisories. Upgrading is the honest
+        # fix; waiving a real advisory because it is inconvenient is not.
+        run: |
+          python -m pip install --upgrade pip setuptools wheel
+          pip install -e ".[all,dev]"
+
+      - name: Lint
+        run: ruff check src tests
+
+      - name: Format
+        run: ruff format --check src tests
+
+      - name: Types
+        run: mypy src
+
+      - name: Tests
+        run: pytest -q
+
+      # A framework shipping opinionated auth and storage defaults should audit
+      # its own dependency tree. Both are hard gates.
+      #
+      # When a finding lands on an unrelated pull request, the order is: try
+      # upgrading the package first, and only if it cannot be upgraded, waive
+      # it here explicitly -- `pip-audit --ignore-vuln PYSEC-0000-000` with a
+      # comment saying which code path makes it inapplicable. Same for bandit
+      # with `# nosec BXXX` and the reason on the line above. What must not
+      # happen is a step going yellow and being ignored, which is how a
+      # security check stops meaning anything.
+      - name: Audit dependencies
+        # --skip-editable: this project is installed from the checkout and is
+        # not on PyPI, so there is nothing to look up for it.
+        run: pip-audit --skip-editable --desc
+
+      - name: Static security scan
+        run: bandit -c pyproject.toml -r src -ll
+
+      # The generator is the part most likely to break silently: templates
+      # render fine but produce code that does not import, or a Jinja
+      # environment eats the runtime braces a Vue file needs. Both smoke
+      # scripts render real trees and run what they produce.
+      - name: Scaffold smoke
+        run: bash scripts/smoke.sh
+
+      - name: Contracts smoke
+        run: bash scripts/smoke_contracts.sh
+
+      - name: Auth and Kubernetes smoke
+        run: bash scripts/smoke_auth_k8s.sh
+
+      - name: Storage, tenancy and serverless smoke
+        run: bash scripts/smoke_storage_tenancy.sh
+
+      - name: Workspace smoke
+        run: bash scripts/smoke_workspace.sh
+
+      - name: Quickstart smoke
+        # The documented commands, run exactly as documented. Docs that have
+        # never been executed are a guess.
+        run: bash scripts/smoke_docs.sh
+
+      - name: Docs site builds and validates
+        run: |
+          pip install -e ".[docs]"
+          python docs-site/build.py --version ci --output site/ci
+          python docs-site/check.py site/ci
+
+  # Generated projects in other languages get their own job, because the
+  # point of generating them is that they build. A scaffold nobody has run
+  # is a liability that looks like a feature.
+  go:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - uses: actions/setup-go@v5
+        with:
+          go-version: "1.23"
+      - run: pip install -e ".[all,dev]"
+      - name: Generate, vet, test, build and run a Go service
+        run: bash scripts/smoke_go.sh
+
+  frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - run: pip install -e ".[all,dev]"
+      - name: Generate, install and build the Vue and React frontends
+        run: bash scripts/smoke_frontend.sh

jfastframework-0.1.0a1/.github/workflows/pages.yml

@@ -0,0 +1,121 @@
+name: Docs site
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  workflow_dispatch:
+
+# Only one deploy at a time, and never cancel one halfway: a cancelled Pages
+# deploy can leave the site partially replaced.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # Tags are needed to build the version picker.
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      - name: Install
+        run: pip install -e ".[docs]"
+
+      - name: Work out the version
+        id: version
+        run: |
+          if [[ "${GITHUB_REF}" == refs/tags/* ]]; then
+            echo "name=${GITHUB_REF#refs/tags/}" >> "$GITHUB_OUTPUT"
+          else
+            echo "name=latest" >> "$GITHUB_OUTPUT"
+          fi
+          # Minor-series directories: v0.3 rather than v0.3.0, so a patch
+          # release replaces its predecessor instead of littering the picker.
+          VERSIONS=$(git tag --list 'v*' --sort=-v:refname \
+            | sed -E 's/^(v[0-9]+\.[0-9]+).*/\1/' | uniq | head -8 | paste -sd, -)
+          echo "all=latest${VERSIONS:+,$VERSIONS}" >> "$GITHUB_OUTPUT"
+
+      - name: Build latest
+        run: |
+          python docs-site/build.py \
+            --version latest \
+            --versions "${{ steps.version.outputs.all }}" \
+            --output site/latest
+
+      - name: Build every released version
+        # The Pages artifact replaces the whole site, so previous versions have
+        # to be rebuilt here or they vanish on the next deploy. Each one is
+        # built from its own tag, which is the point of versioned docs:
+        # someone pinned to 0.3 should read 0.3's documentation.
+        run: |
+          for MINOR in $(git tag --list 'v*' --sort=-v:refname \
+              | sed -E 's/^(v[0-9]+\.[0-9]+).*/\1/' | uniq | head -8); do
+            TAG=$(git tag --list "${MINOR}*" --sort=-v:refname | head -1)
+            echo "::group::${MINOR} (from ${TAG})"
+            rm -rf .worktree
+            git worktree add --detach .worktree "${TAG}" >/dev/null
+            if [ -f .worktree/docs-site/build.py ]; then
+              (cd .worktree && python docs-site/build.py \
+                --version "${MINOR}" \
+                --versions "${{ steps.version.outputs.all }}" \
+                --output "../site/${MINOR}")
+            else
+              echo "no docs-site/ at ${TAG}; skipping"
+            fi
+            git worktree remove --force .worktree
+            echo "::endgroup::"
+          done
+
+      - name: Check every built version
+        # A docs site fails quietly: a broken link still renders as a page.
+        run: |
+          FAILED=0
+          for DIR in site/*/; do
+            echo "checking ${DIR}"
+            python docs-site/check.py "${DIR}" || FAILED=1
+          done
+          exit "${FAILED}"
+
+      - name: Root redirect to latest
+        run: |
+          cat > site/index.html <<'HTML'
+          <!doctype html>
+          <html lang="en">
+          <head>
+            <meta charset="utf-8">
+            <title>JFastFramework</title>
+            <link rel="canonical" href="latest/">
+            <meta http-equiv="refresh" content="0; url=latest/">
+          </head>
+          <body><p><a href="latest/">JFastFramework documentation</a></p></body>
+          </html>
+          HTML
+          # Jekyll would otherwise skip files and directories starting with _.
+          touch site/.nojekyll
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - id: deploy
+        uses: actions/deploy-pages@v4

jfastframework-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+# Publishing runs through PyPI's trusted publishing: GitHub mints a short-lived
+# OIDC token for this exact workflow in this exact repository, and PyPI trades
+# it for an upload. No API token is stored anywhere, so there is none to leak
+# and none to rotate.
+#
+# Registering it on PyPI means filling in, exactly:
+#
+#   Owner              JFabrizzio5
+#   Repository name    JFastFramework
+#   Workflow name      release.yml
+#   Environment name   pypi          (testpypi, on test.pypi.org)
+#
+# The environment names below have to match what is registered there, or the
+# token is minted for a claim PyPI will not accept.
+
+on:
+  workflow_dispatch:
+    inputs:
+      target:
+        description: Where to publish
+        type: choice
+        options: [testpypi, pypi]
+        default: testpypi
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: pipx run build
+
+      # --strict fails on a malformed long description, which is the failure
+      # that otherwise shows up as a blank project page after the upload has
+      # already happened and the version is burned.
+      - name: Check the metadata
+        run: pipx run twine check --strict dist/*
+
+      # A sdist that does not install is only discovered by someone else.
+      - name: Install the built wheel and run the CLI
+        run: |
+          python -m venv /tmp/probe
+          /tmp/probe/bin/pip install --quiet dist/*.whl
+          /tmp/probe/bin/jfast version
+          /tmp/probe/bin/python -c "import jfastframework; print(jfastframework.__version__)"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  testpypi:
+    needs: build
+    if: github.event_name == 'workflow_dispatch' && inputs.target == 'testpypi'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          # TestPyPI keeps old uploads from experiments; re-running a build
+          # that produced identical files should not fail the job.
+          skip-existing: true
+
+  pypi:
+    needs: build
+    if: >-
+      github.event_name == 'push'
+      || (github.event_name == 'workflow_dispatch' && inputs.target == 'pypi')
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

jfastframework-0.1.0a1/.gitignore

@@ -0,0 +1,32 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.python-version
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+
+# Env
+.env
+.env.local
+.env.*.local
+
+# Generated deploy artifacts
+/generated/
+docker-compose.generated.yml
+
+# OS
+.DS_Store
+
+# Generated documentation site
+/site/

jfastframework-0.1.0a1/.jfast/skills/README.md

@@ -0,0 +1,65 @@
+# Skills
+
+A skill is a folder holding one `SKILL.md`: instructions for a task an agent
+performs repeatedly in this codebase.
+
+The point is selective loading. An agent should not read the entire manual to
+add one module — it reads the front matter of each skill, picks the one that
+matches, and loads only that file.
+
+## Layout
+
+```
+.jfast/skills/
+├── README.md
+├── add-service/SKILL.md        add a service: datastores, ports, gateway
+├── respect-contracts/SKILL.md  read the project contract, then verify against it
+├── create-module/SKILL.md      scaffold a domain module: layout, UI, wiring
+├── create-plugin/SKILL.md      build a plugin that adds a capability
+├── build-frontend/SKILL.md     UI: server-rendered HTMX, or a Vue/React SPA
+├── add-rag/SKILL.md            semantic search over pgvector or Qdrant
+└── design-system/SKILL.md      apply a DESIGN.md to generated UI
+```
+
+The first decision an agent makes is usually **service or module**, and getting
+it wrong is expensive in one direction only: a module promoted to a service
+later is a move, while a premature service is a network hop, a second deploy
+target and an integration test nobody asked for. `add-service` opens with that
+question for exactly that reason.
+
+## Format
+
+Front matter, then the steps.
+
+```markdown
+---
+name: create-module
+description: Scaffold a domain module. Use when adding a new business entity
+  with its own table and endpoints.
+when_to_use: The user asks for a new resource, entity, CRUD surface, or table.
+when_not_to_use: The change fits inside an existing module, or adds a
+  cross-cutting capability (that is a plugin).
+---
+
+## Steps
+1. ...
+```
+
+`description` and `when_to_use` are the routing signal. Write them so an agent
+can decide from those two lines alone whether to open the file.
+
+## Rules
+
+- One task per skill. If a skill has two "or else" branches, it is two skills.
+- Give exact commands, not descriptions of commands.
+- State the verification step. A skill that does not say how to check its own
+  output produces work nobody validated.
+- Keep it under 150 lines. Longer means the task is not decomposed.
+
+## Related conventions
+
+- `DESIGN.md` next to a module or frontend describes the visual language:
+  palette, type scale, spacing, component patterns. The `design-system` skill
+  consumes it.
+- `AGENTS.md` at the repository root holds rules that apply to every task.
+  Skills hold rules for one task. Do not duplicate between them.

jfastframework-0.1.0a1/.jfast/skills/add-rag/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: add-rag
+description: Enable semantic search over pgvector or Qdrant, with a local
+  Ollama embedder or a custom one.
+when_to_use: The user wants semantic search, a knowledge base, "chat with my
+  documents", or retrieval to ground an LLM answer.
+when_not_to_use: Exact-match or keyword search is enough — use a PostgreSQL
+  index or full-text search. RAG is not a substitute for a WHERE clause.
+---
+
+## What you get
+
+`POST /rag/documents` (ingest), `POST /rag/search`, `DELETE /rag/documents/{id}`,
+plus `rag.store` and `rag.embedder` providers for code that needs them
+directly.
+
+## Known limits — say these before building on it
+
+- Chunking is fixed-size with overlap. Fine for prose, poor for code and tables.
+- No reranking. Top-k by cosine similarity only.
+- No hybrid search. Pure vector, no BM25 blend.
+- `auto_migrate` runs DDL at startup. Fine in development; move to migrations
+  before production.
+
+If the use case needs better retrieval than that, say so rather than shipping
+this and calling it done.
+
+## Step 1: choose the store
+
+| | pgvector (default) | Qdrant |
+| --- | --- | --- |
+| Operational cost | none — the database you already run | a second service to run and back up |
+| Scale | comfortable to a few million chunks | far beyond |
+| Filtering | tenant id, plus whatever SQL you write | rich indexed payload filters |
+
+**Start with pgvector.** Move to Qdrant when you hit a wall you can name —
+filter complexity, index build time, memory. "It might scale better" is not
+that wall.
+
+## Step 2: enable the plugins
+
+pgvector:
+
+```bash
+pip install -e ".[rag,db]"
+```
+
+```toml
+[plugins]
+enabled = ["observability", "database", "rag"]
+
+[plugin.rag]
+store = "pgvector"
+collection = "rag_chunks"
+dimensions = 768
+chunk_size = 1000
+chunk_overlap = 150
+top_k = 5
+```
+
+Qdrant:
+
+```bash
+pip install -e ".[rag,qdrant]"
+```
+
+```toml
+[plugins]
+enabled = ["observability", "qdrant", "rag"]
+
+[plugin.rag]
+store = "qdrant"
+collection = "rag_chunks"
+dimensions = 768
+```
+
+Getting this pairing wrong fails at startup with the fix in the message, not at
+the first search:
+
+```
+rag store 'qdrant' needs the 'qdrant' plugin. Add "qdrant" to [plugins].enabled.
+```
+
+## Step 3: match dimensions to the model
+
+The mistake that costs an afternoon. `nomic-embed-text` is 768;
+`mxbai-embed-large` is 1024. A mismatch fails at insert, and changing it later
+means re-embedding everything already ingested. Decide before the first ingest.
+
+```bash
+ollama pull nomic-embed-text
+curl -s localhost:11434/api/tags | jq -r '.models[].name'
+```
+
+For pgvector, the image must carry the extension — `pgvector/pgvector:pg16`,
+which the `database` plugin already defaults to.
+
+## Step 4: ingest and search
+
+```bash
+curl -X POST localhost:8000/rag/documents \
+  -H 'content-type: application/json' \
+  -d '{"document_id":"doc-1","content":"...","metadata":{"source":"manual"}}'
+
+curl -X POST localhost:8000/rag/search \
+  -H 'content-type: application/json' \
+  -d '{"query":"how do refunds work","limit":5}'
+```
+
+Re-ingesting a document replaces its chunks in both stores — pgvector deletes
+by `document_id`, Qdrant derives point ids deterministically from
+`(document_id, chunk_index)`.
+
+## Swapping the embedder
+
+Implement the protocol — a `dimensions` attribute and an async
+`embed(texts) -> list[list[float]]` — then:
+
+```toml
+[plugin.rag]
+embedder = "myapp.embeddings:OpenAIEmbedder"
+```
+
+A custom store works the same way (`store = "myapp.stores:MyStore"`); it is
+constructed with the `AppContext`, so it can pull its client from the provider
+registry.
+
+## Multi-tenancy
+
+Pass `tenant_id` on ingest and search. Both stores filter on it and index it.
+Until row-level security lands (PLAN.md phase 2) that filter is a convention:
+a caller that omits `tenant_id` searches across tenants. If the data is
+tenant-sensitive, set the value server-side from the JWT — never from the
+request body.
+
+## Verification
+
+```bash
+jfast doctor
+curl -s localhost:8000/ready | jq '.checks.rag'
+```
+
+Then ingest one known document and search for a phrase inside it. If the top
+result is not that document, the embedder or the dimensions are wrong — check
+those before touching `chunk_size`.