Rewrite handlers.llm module

.github/workflows/nightly_examples.yml

@@ -0,0 +1,50 @@
+name: Nightly Examples
+
+# Every example in docs/source/llm_examples, run against a live model with its
+# own default arguments.
+#
+# Pull requests get two cheaper checks: the Test workflow proves every example
+# still imports and parses its flags (no API key needed), and the LLM
+# Integration Tests workflow runs basics/ live. This is where the rest -- the
+# agent searches and multi-round pipelines marked nightly_example -- get run,
+# nightly, where a flake costs a re-run rather than a blocked PR.
+
+on:
+  schedule:
+    # 07:00 UTC, after the US evening and before the European morning.
+    - cron: "0 7 * * *"
+  workflow_dispatch:
+    inputs:
+      model:
+        description: "Model to run the examples against"
+        required: false
+        default: "gpt-4o-mini"
+
+jobs:
+  examples:
+    runs-on: ubuntu-latest
+    timeout-minutes: 180
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install Python dependencies
+        run: uv sync --all-extras --dev
+
+      # No -m filter: the nightly is the run that covers everything. Each
+      # example is a subprocess, so xdist gets real parallelism across them.
+      - name: Run every example
+        env:
+          EFFECTFUL_LLM_MODEL: ${{ github.event.inputs.model || 'gpt-4o-mini' }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          uv run pytest tests/test_handlers_llm_examples.py -v -n logical

.github/workflows/publish_docs.yml

@@ -34,10 +34,6 @@ jobs:
     - name: Build docs
       run: cd docs && uv run make html
 
-    - name: Generate LLM agent reference markdown
-      run: |
-        uv run jupyter nbconvert --to markdown docs/source/llm.ipynb --output llm.md --output-dir docs/build/html/
-
     - name: Setup Pages
       uses: actions/configure-pages@v4
 

.github/workflows/test.yml

@@ -26,7 +26,9 @@ jobs:
           - name: numpyro
             paths: tests/test_handlers_numpyro*.py
           - name: llm
-            paths: tests/test_handlers_llm*.py
+            paths: tests/test_handlers_llm*.py -k "not mypy"
+          - name: llm-mypy
+            paths: tests/test_handlers_llm*.py -k "mypy"
           - name: examples
             paths: tests/test_examples_*.py
           - name: core

.github/workflows/test_docs.yml

@@ -33,7 +33,3 @@ jobs:
       - name: Build docs
         run: |
           cd docs && uv run make html
-
-      - name: Generate LLM agent reference markdown
-        run: |
-          uv run jupyter nbconvert --to markdown docs/source/llm.ipynb --output llm.md --output-dir docs/build/html/

.github/workflows/test_llm.yml

@@ -12,9 +12,12 @@ jobs:
   test-llm:
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         python-version: ["3.13", "3.14"]
         model: ["gpt-4o-mini"]
+        mypy: ["mypy", "not mypy"]
+    name: "test-llm (py ${{ matrix.python-version }}, ${{ matrix.mypy }})"
     steps:
       - uses: actions/checkout@v4
 
@@ -37,4 +40,35 @@ jobs:
           OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
           ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
         run: |
-          uv run pytest tests/test_handlers_llm_provider.py tests/test_handlers_llm_tool_calling_poem.py tests/test_handlers_llm_tool_calling_book.py tests/test_handlers_llm_encoding.py -v --tb=short
+          uv run pytest tests/test_handlers_llm_* -v -n logical \
+            -m "not example" -k "${{ matrix.mypy }}"
+
+  # The basics/ examples, run live the way a reader runs them.
+  examples:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    name: "basics examples (live)"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          enable-cache: true
+          python-version: "3.13"
+
+      - name: Set up Python
+        run: uv python install
+
+      - name: Install Python dependencies
+        run: |
+          uv sync --all-extras --dev
+
+      - name: Run the basics examples
+        env:
+          EFFECTFUL_LLM_MODEL: gpt-4o-mini
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+        run: |
+          uv run pytest tests/test_handlers_llm_examples.py -v -n logical \
+            -m "not nightly_example"

README.rst

@@ -131,7 +131,7 @@ Claude Code, Cursor, Copilot) to:
    https://basisresearch.github.io/effectful/llm.md
 
 This file is auto-generated from the `LLM tutorial notebook <https://basisresearch.github.io/effectful/llm.html>`_
-and contains complete API usage examples for templates, tool calling,
+and contains complete API usage examples for skills, tool calling,
 structured output, retries, and more.
 
 Learn More

docs/source/conf.py

@@ -44,6 +44,12 @@
 # Enable documentation inheritance
 autodoc_inherit_docstrings = True
 
+# Render the ``__init__`` docstring alongside the class docstring.  The LLM
+# harness handlers rely on this split: a handler's class docstring is injected
+# into the model's system prompt, so constructor documentation -- which only
+# the caller of ``Handler(...)`` can act on -- lives on ``__init__`` instead.
+autoclass_content = "both"
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #

docs/source/effectful.rst

@@ -47,35 +47,172 @@ LLM
    :members:
    :undoc-members:
 
-Template
-""""""""
+Types
+"""""
 
-.. automodule:: effectful.handlers.llm.template
+.. automodule:: effectful.handlers.llm.types
    :members:
    :undoc-members:
 
-Encoding
-""""""""
+Harness
+"""""""
 
-.. automodule:: effectful.handlers.llm.encoding
+.. automodule:: effectful.handlers.llm.harness
    :members:
    :undoc-members:
 
-Completions
-"""""""""""
-      
-.. automodule:: effectful.handlers.llm.completions
+Command-line launcher
+~~~~~~~~~~~~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.__main__
    :members:
    :undoc-members:
 
-Evaluation
-""""""""""
-      
-.. automodule:: effectful.handlers.llm.evaluation
+Hooks
+~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.hooks
    :members:
    :undoc-members:
 
-
+Serialization
+~~~~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.serialization
+   :members:
+   :undoc-members:
+
+Provision
+~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.provision
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.provision.litellm
+   :members:
+   :undoc-members:
+
+Legibility
+~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.legibility
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.legibility.framework
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.legibility.lexical
+   :members:
+   :undoc-members:
+
+Execution
+~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.execution
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.execution.hooks
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.execution.builtin
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.execution.restricted
+   :members:
+   :undoc-members:
+   :private-members:
+
+Validation
+~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.validation
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.validation.hooks
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.validation.pydantic
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.validation.mypy
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.validation.ty
+   :members:
+   :undoc-members:
+
+Synthesis
+~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.synthesis
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.synthesis.snippet
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.synthesis.function
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.synthesis.body
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.synthesis.toolcall
+   :members:
+   :undoc-members:
+
+Durability
+~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.durability
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.durability.transaction
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.durability.retrying
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.durability.persistence
+   :members:
+   :undoc-members:
+
+Observability
+~~~~~~~~~~~~~
+
+.. automodule:: effectful.handlers.llm.harness.observability
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.observability.rich
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.observability.dump
+   :members:
+   :undoc-members:
+
+.. automodule:: effectful.handlers.llm.harness.observability.langfuse
+   :members:
+   :undoc-members:
+
+
 Jax
 ^^^
 

docs/source/index.rst

@@ -8,13 +8,6 @@ Table of Contents
    getting_started
    introduction
    named_tensor_notation
-   llm
-
-.. tip::
-
-   **For AI coding agents:** A standalone Markdown version of the LLM guide is
-   available at `llm.md <llm.md>`_ — point your agent there for a complete
-   reference on building effectful LLM applications.
 
 .. toctree::
    :maxdepth: 1