lauren 1.0.0__tar.gz

lauren-1.0.0/.editorconfig

@@ -0,0 +1,26 @@
+# EditorConfig — https://editorconfig.org
+# Unifies whitespace settings across editors and AI coding agents.
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+max_line_length = 88
+
+[*.py]
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+max_line_length = 80
+
+[Makefile]
+indent_style = tab

lauren-1.0.0/.github/CODEOWNERS

@@ -0,0 +1,24 @@
+# CODEOWNERS — auto-request reviews from these owners on PRs.
+# See https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-security/customizing-your-repository/about-code-owners
+#
+# Replace the placeholder team / users below with the actual maintainers
+# (e.g. @lauren-framework/core, @your-handle) once the repo is published.
+
+# Default owner — every file unless overridden below.
+*                       @lauren-framework/maintainers
+
+# Critical subsystems — keep an extra reviewer in the loop.
+/lauren/_asgi/          @lauren-framework/runtime
+/lauren/_di/            @lauren-framework/runtime
+/lauren/_routing/       @lauren-framework/runtime
+
+# Documentation and the AI-readable refs.
+/docs/                  @lauren-framework/docs
+/README.md              @lauren-framework/docs
+/llms.txt               @lauren-framework/docs
+/llms-full.txt          @lauren-framework/docs
+
+# CI / build / release pipeline.
+/.github/               @lauren-framework/maintainers
+/noxfile.py             @lauren-framework/maintainers
+/pyproject.toml         @lauren-framework/maintainers

lauren-1.0.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,133 @@
+name: 🐞 Bug report
+description: Report a defect — something doesn't work the way the docs / `llms-full.txt` / type hints say it should.
+title: "[bug]: <one-line summary>"
+labels: ["bug", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to file a precise bug report.
+
+        Before submitting, please:
+
+        1. Search [open](https://github.com/lauren-framework/lauren/issues?q=is%3Aissue+is%3Aopen+label%3Abug) and [closed](https://github.com/lauren-framework/lauren/issues?q=is%3Aissue+is%3Aclosed+label%3Abug) bug reports.
+        2. Reproduce on the **latest** `main` if at all possible (`pip install git+https://github.com/lauren-framework/lauren@main`).
+        3. Strip your reproducer down to the smallest self-contained snippet.
+
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: One or two sentences describing the bug.
+      placeholder: e.g. "`Json[Model]` extractor raises `TypeError` when the model has a `ForwardRef` annotation."
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproducer
+    attributes:
+      label: Minimal reproducer
+      description: |
+        A self-contained Python snippet that reproduces the bug. Prefer code that I can paste directly into a file and run with `python repro.py` or `pytest repro.py`. Include any `curl`/`httpx` commands needed.
+      render: python
+      placeholder: |
+        from lauren import LaurenFactory, controller, get, module, Json
+        # ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+      description: What did you expect to happen, and *why* (cite the README, docs, llms-full.txt, or a type hint where applicable)?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual behavior
+      description: |
+        What happened instead? Paste the full traceback inside a fenced code block. If the bug is a wrong response, paste the request and the response.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: lauren-version
+    attributes:
+      label: lauren version
+      description: Output of `python -c "import lauren; print(lauren.__version__)"` (or the commit SHA if installed from `main`).
+      placeholder: e.g. 1.0.0 or main@abc1234
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      description: Output of `python --version`.
+      placeholder: e.g. 3.12.4
+    validations:
+      required: true
+
+  - type: input
+    id: pydantic-version
+    attributes:
+      label: Pydantic version
+      description: Output of `python -c "import pydantic; print(pydantic.VERSION)"`.
+      placeholder: e.g. 2.8.2
+    validations:
+      required: true
+
+  - type: dropdown
+    id: os
+    attributes:
+      label: Operating system
+      options:
+        - Linux
+        - macOS
+        - Windows
+        - Other (please describe in "Additional context")
+    validations:
+      required: true
+
+  - type: dropdown
+    id: severity
+    attributes:
+      label: Severity
+      description: Your best guess — maintainers may re-classify.
+      options:
+        - "Critical: data loss, security, or app cannot start"
+        - "High: a documented feature is broken; no workaround"
+        - "Medium: documented feature is broken; workaround exists"
+        - "Low: incorrect error message, type hint, or doc"
+      default: 2
+    validations:
+      required: true
+
+  - type: textarea
+    id: regression
+    attributes:
+      label: Regression (if applicable)
+      description: Did this work in a previous version? If so, which one was the last good version? `git bisect` is welcome.
+      placeholder: e.g. Worked in 0.9.x, broken in 1.0.0.
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Anything else — full ASGI server, deployment topology, related issues, screenshots.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I have searched the existing issues and could not find a duplicate.
+          required: true
+        - label: I have read [`CONTRIBUTING.md`](https://github.com/lauren-framework/lauren/blob/main/CONTRIBUTING.md) and [`AGENTS.md`](https://github.com/lauren-framework/lauren/blob/main/AGENTS.md).
+          required: true
+        - label: My reproducer runs in a clean virtualenv with the dependencies I list above.
+          required: true

lauren-1.0.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: false
+contact_links:
+  - name: 💬 Question / Discussion
+    url: https://github.com/lauren-framework/lauren/discussions
+    about: Ask a question, share an idea, or start a design discussion. Please use Discussions instead of Issues for questions.
+  - name: 📚 Documentation
+    url: https://lauren-framework.github.io/lauren/
+    about: Read the documentation, including the AI-readable llms.txt and llms-full.txt references.
+  - name: 🛡️ Security advisory (private)
+    url: https://github.com/lauren-framework/lauren/security/advisories/new
+    about: Report a security vulnerability privately via GitHub Security Advisories. DO NOT open a public issue for security problems.

lauren-1.0.0/.github/ISSUE_TEMPLATE/documentation.yml

@@ -0,0 +1,64 @@
+name: 📚 Documentation issue
+description: Report a problem with the docs, README, llms.txt, llms-full.txt, or examples.
+title: "[docs]: <one-line summary>"
+labels: ["documentation", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping keep the documentation honest! Documentation
+        bugs include wrong code samples, broken links, missing entries in
+        `llms-full.txt`, or sections that contradict the implementation.
+
+  - type: dropdown
+    id: location
+    attributes:
+      label: Where is the issue?
+      multiple: true
+      options:
+        - "README.md"
+        - "Documentation site (mkdocs)"
+        - "llms.txt"
+        - "llms-full.txt"
+        - "AGENTS.md / .CLAUDE.md"
+        - "CONTRIBUTING.md"
+        - "Docstrings / `__doc__`"
+        - "IDEAS.md"
+        - "Other (please specify)"
+    validations:
+      required: true
+
+  - type: input
+    id: url-or-path
+    attributes:
+      label: URL or file path
+      description: A direct link to the affected page or a path inside the repo.
+      placeholder: e.g. docs/core-concepts/extractors.md, or https://lauren-framework.github.io/lauren/guides/middleware/
+    validations:
+      required: true
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: What's wrong?
+      description: |
+        Describe the issue. If a code sample doesn't work, paste the snippet, the command you ran, and the error.
+    validations:
+      required: true
+
+  - type: textarea
+    id: suggestion
+    attributes:
+      label: Suggested wording (optional)
+      description: |
+        If you'd like to propose specific wording, paste it here. Markdown is welcome. PRs welcome too!
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I have searched existing documentation issues for duplicates.
+          required: true
+        - label: If a code sample is wrong, I verified that it actually fails on the latest `main`.
+          required: false

lauren-1.0.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,105 @@
+name: ✨ Feature request
+description: Propose a new feature, decorator, extractor, or behavior.
+title: "[feature]: <one-line summary>"
+labels: ["enhancement", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for proposing a feature! Please remember the project's
+        design philosophy from [`.CLAUDE.md`](https://github.com/lauren-framework/lauren/blob/main/.CLAUDE.md):
+
+        > **Startup validates; runtime dispatches.**
+        > Decorators attach metadata; they never rewrite functions.
+        > No reflection on the request path. Pre-compile everything.
+
+        Feature requests that violate these invariants are unlikely to land
+        even if useful — please propose a design that respects them, or
+        explain why the invariant should be relaxed.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem / motivation
+      description: |
+        Describe the problem you're trying to solve. Include the user-facing pain — "I want to do X but currently have to write Y" — *not* the solution. Concrete code that fails or is awkward today is gold.
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposed-api
+    attributes:
+      label: Proposed API
+      description: |
+        Sketch the public-facing API (Python code) that you would like to write. Include decorators, type hints, and at least one realistic example.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Behavior & invariants
+      description: |
+        Spell out the runtime behavior, including edge cases, what should happen at startup vs. on each request, and any new validation that would run inside `LaurenFactory.create(...)`.
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: |
+        What other approaches did you consider, and why did you reject them? "I checked Axum / NestJS / FastAPI / Litestar and they do X" is welcome and useful.
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: Which subsystem(s) does this touch?
+      multiple: true
+      options:
+        - Routing (`lauren/_routing`)
+        - Dependency Injection (`lauren/_di`)
+        - Modules (`lauren/_modules`)
+        - Lifecycle (`lauren/_lifecycle`)
+        - ASGI runtime (`lauren/_asgi`)
+        - Extractors / typing (`lauren/_typing`)
+        - OpenAPI generation
+        - Middleware / guards
+        - Logging
+        - Documentation
+        - Tooling / build / CI
+    validations:
+      required: true
+
+  - type: dropdown
+    id: breaking
+    attributes:
+      label: Breaking change?
+      options:
+        - "No — pure addition"
+        - "No — addition with deprecation of an alternative"
+        - "Yes — would require a major version bump"
+        - "Unsure — please advise"
+      default: 0
+    validations:
+      required: true
+
+  - type: textarea
+    id: extra
+    attributes:
+      label: Additional context
+      description: Links to similar features in other frameworks, prior art, RFCs, or Discussions.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: I have read the design philosophy in [`.CLAUDE.md`](https://github.com/lauren-framework/lauren/blob/main/.CLAUDE.md) / [`AGENTS.md`](https://github.com/lauren-framework/lauren/blob/main/AGENTS.md).
+          required: true
+        - label: I have searched [`IDEAS.md`](https://github.com/lauren-framework/lauren/blob/main/IDEAS.md) and existing issues for prior art on this idea.
+          required: true
+        - label: I have considered alternatives and explained why this proposal is preferable.
+          required: true

lauren-1.0.0/.github/ISSUE_TEMPLATE/performance.yml

@@ -0,0 +1,82 @@
+name: 🐢 Performance regression
+description: Report unexpected latency, memory, or throughput regressions.
+title: "[perf]: <one-line summary>"
+labels: ["performance", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        lauren has strong performance invariants — no reflection on the
+        request path, per-request DI cache, immutable execution graph.
+        If you've measured a regression against those guarantees we want
+        to know.
+
+        Please make sure your numbers come from a **warm** process
+        (discard the first ~1k requests) and that you're comparing
+        like-for-like (same Python version, same Pydantic version,
+        same number of workers, same hardware).
+
+  - type: textarea
+    id: scenario
+    attributes:
+      label: Scenario
+      description: What route / endpoint / startup step is slow? Paste the controller and the request.
+      render: python
+    validations:
+      required: true
+
+  - type: textarea
+    id: numbers
+    attributes:
+      label: Measurements
+      description: |
+        Show the numbers: p50/p95/p99 latency, RPS, memory, or startup time. Include the benchmarking command and any flags. `wrk`, `oha`, `bombardier`, `pytest-benchmark`, or a self-rolled `asyncio` harness are all welcome.
+      render: text
+    validations:
+      required: true
+
+  - type: input
+    id: baseline
+    attributes:
+      label: Baseline (good) version
+      description: Last lauren version where the numbers were acceptable, if known.
+      placeholder: e.g. 1.0.0
+
+  - type: input
+    id: regressed
+    attributes:
+      label: Regressed (bad) version
+      description: First lauren version where the regression appeared.
+      placeholder: e.g. main@abc1234
+    validations:
+      required: true
+
+  - type: textarea
+    id: env
+    attributes:
+      label: Environment
+      description: |
+        - Python version
+        - Pydantic version
+        - ASGI server + version (`uvicorn 0.30`, `hypercorn`, `granian`, …)
+        - OS + arch
+        - CPU / RAM / container limits
+    validations:
+      required: true
+
+  - type: textarea
+    id: profile
+    attributes:
+      label: Profile / flamegraph (optional but very welcome)
+      description: |
+        Output of `py-spy`, `cProfile`, `perf`, or `austin` on the slow path. Drag-and-drop SVGs are fine.
+
+  - type: checkboxes
+    id: terms
+    attributes:
+      label: Pre-flight checklist
+      options:
+        - label: My measurements were taken on a warm process (steady-state, not cold-start).
+          required: true
+        - label: I have isolated lauren — i.e., the slow path doesn't include my own database / network calls.
+          required: true

lauren-1.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,61 @@
+<!--
+Thanks for sending a pull request!
+
+Please read CONTRIBUTING.md and AGENTS.md / .CLAUDE.md before opening
+this PR — they contain the design invariants reviewers use to accept or
+reject changes.
+-->
+
+## Summary
+
+<!-- One paragraph describing *what* this PR does and *why*. -->
+
+## Linked issues
+
+<!-- Use "Closes #123" / "Fixes #123" / "Refs #123" syntax. -->
+
+Closes #
+
+## Type of change
+
+- [ ] 🐞 Bug fix (non-breaking change that fixes a defect)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 💥 Breaking change (would require a major version bump)
+- [ ] 📚 Documentation only
+- [ ] 🧹 Refactor / internal cleanup (no behavior change)
+- [ ] ⚡ Performance improvement
+- [ ] 🧪 Test-only change
+- [ ] 🛠️ Build / CI / tooling
+
+## Design checklist
+
+> See [`.CLAUDE.md`](../.CLAUDE.md) — these invariants are *not* optional.
+
+- [ ] **Startup validates; runtime dispatches.** Any new misuse fails inside `LaurenFactory.create(...)`, not on the first request.
+- [ ] **Decorators attach metadata; they don't rewrite functions.** No `functools.wraps` mutation of the user's callable.
+- [ ] **No reflection on the request path.** All `inspect.signature(...)`, `get_type_hints(...)`, etc. happen at startup.
+- [ ] Every public name is exported in `__all__` *and* documented in `llms-full.txt`.
+- [ ] Type hints are tight and `mypy --strict` clean for the affected modules.
+
+## Tests
+
+- [ ] I added at least one test that fails on `main` and passes here, OR this PR is test/docs-only.
+- [ ] `nox -s tests` passes locally.
+- [ ] `nox -s coverage` does not lower coverage on the touched modules.
+
+## Documentation
+
+- [ ] I updated `README.md` if the public surface changed.
+- [ ] I updated `llms-full.txt` for any new/changed public symbol.
+- [ ] I updated the mkdocs site (`docs/`) if there's a user-facing concept change.
+
+## Reviewer notes
+
+<!--
+Anything subtle reviewers should look at first? Tricky concurrency? A
+deliberate behavior change that might surprise users?
+-->
+
+## Screenshots / logs (optional)
+
+<!-- For perf or DX changes, paste before/after numbers here. -->

lauren-1.0.0/.github/dependabot.yml

@@ -0,0 +1,36 @@
+version: 2
+updates:
+  # GitHub Actions versions in our workflows.
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Etc/UTC"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "ci"
+    labels:
+      - "dependencies"
+      - "ci"
+
+  # Python runtime + dev dependencies declared in pyproject.toml.
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+      time: "06:00"
+      timezone: "Etc/UTC"
+    open-pull-requests-limit: 5
+    commit-message:
+      prefix: "deps"
+    labels:
+      - "dependencies"
+    # Group patch / minor updates so we don't get one PR per dep per week.
+    groups:
+      python-minor-and-patch:
+        update-types:
+          - "minor"
+          - "patch"

lauren-1.0.0/.github/workflows/codeql.yml

@@ -0,0 +1,40 @@
+name: codeql
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    # Re-scan weekly to pick up new advisories.
+    - cron: "37 5 * * 1"
+  workflow_dispatch:
+
+concurrency:
+  group: codeql-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze (${{ matrix.language }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [python]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+          queries: +security-and-quality
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3
+        with:
+          category: "/language:${{ matrix.language }}"

lauren-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "mkdocs.yml"
+      - "docs-requirements.txt"
+      - "README.md"
+      - "CHANGELOG.md"
+      # Rebuild when source changes so mkdocstrings API reference stays fresh.
+      - "lauren/**"
+      - ".github/workflows/docs.yml"
+      - "noxfile.py"
+  workflow_dispatch:
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  # Needed for the deploy job below.
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    name: Build docs (strict)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        run: |
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install nox
+      - name: Re-generate plain-Markdown API reference (for lauren-website)
+        run: |
+          pip install griffe
+          python scripts/generate_api_docs.py
+      - name: Build site
+        run: nox -s docs
+      - name: Upload site artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: site
+          path: site/
+          retention-days: 14
+      - name: Upload Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/
+
+  # deploy:
+  #   name: Deploy to GitHub Pages
+  #   if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+  #   needs: build
+  #   runs-on: ubuntu-latest
+  #   environment:
+  #     name: github-pages
+  #     url: ${{ steps.deployment.outputs.page_url }}
+  #   steps:
+  #     - id: deployment
+  #       uses: actions/deploy-pages@v4