langfuse-hotswap 0.1.0__tar.gz

langfuse_hotswap-0.1.0/.claude/rules/config-security.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "src/langfuse_hotswap/_config.py"
+  - "src/langfuse_hotswap/_factory.py"
+---
+
+# Model parameters and their security
+
+Anyone who can edit a prompt in Langfuse controls its config. These rules keep that from
+becoming control over endpoints, credentials or cost.
+
+- Precedence is fixed: prompt config < factory kwargs < provider kwargs. Never let the config
+  override something set in code.
+- The provider comes only from an explicit `model_provider`. Do not infer it from the model name
+  and do not parse a `provider:model` prefix. The model name is passed as is.
+- With `providers` set, the config may select only one of those providers.
+- `DEFAULT_ALLOWED_CONFIG_KEYS` holds sampling parameters only. Infrastructure (timeouts,
+  retries, endpoints, clients, credentials) never goes there.
+- `is_blocked_config_key` is the second line of defense and applies even with
+  `allowed_config_keys=None`. When adding a provider-specific infrastructure argument, block it by
+  exact name or by a prefix/suffix rule, and add it to the blocked-keys test in `test_config.py`.
+- `build_model_params` stays a pure function: no I/O, no logging, no model construction.

langfuse_hotswap-0.1.0/.claude/rules/docs-and-ci.md

@@ -0,0 +1,29 @@
+---
+paths:
+  - "README.md"
+  - "CLAUDE.md"
+  - ".claude/rules/**"
+  - ".github/workflows/**"
+---
+
+# Documentation and CI
+
+## README
+
+- The README is the user documentation and holds the rationale that docstrings leave out.
+- A change in behavior, defaults or the public API updates the README in the same change.
+- Code samples in the README must run against the current API.
+
+## CLAUDE.md and rules
+
+- Written in English, the whole file.
+- `CLAUDE.md` stays short: commands, layout, invariants. Detailed rules go to `.claude/rules/`
+  with a `paths` front matter that limits them to the files they are about.
+
+## GitHub Actions
+
+- Pin every action to a full commit SHA with the version in a comment.
+- Default `permissions: contents: read`; grant more per job only where needed.
+- `actions/checkout` uses `persist-credentials: false`.
+- The release builds and tests in a job without `id-token`; only the publish job gets
+  `id-token: write`, and it runs no project code.

langfuse_hotswap-0.1.0/.claude/rules/python-style.md

@@ -0,0 +1,35 @@
+---
+paths:
+  - "**/*.py"
+---
+
+# Python style
+
+## Docstrings
+
+- Every docstring is multi-line: `"""` on its own line, the text, `"""` on its own line. No one-line form.
+- In a function or method, one blank line separates the docstring from the code that follows.
+- A docstring says what the object does or returns, in one or two sentences. Behavior that the
+  caller must know (precedence, defaults, what is raised) may follow as a short second paragraph.
+- No reasoning, consequences or motivation ("so that", "because", "this means"). The rationale
+  belongs in the README or, when it is local and non-obvious, in a one-line code comment.
+- Methods that implement the `Runnable` interface as is (`invoke`, `stream`, …) have no docstring.
+
+## Layout of code
+
+- Separate the logical steps of a function with one blank line: validation, computation, the
+  result. Do not separate lines that form one step.
+- A predicate used in a condition gets its own method or function when it has more than two
+  clauses (see `_cache_is_warm`).
+- Group a module as: module docstring, imports, type variables, logger, private helper types,
+  public classes, module-level helper functions.
+- Pure logic that does not need the runnable state belongs in its own module (see `_config.py`).
+
+## Code
+
+- No `__all__`. The public API is whatever `__init__.py` imports.
+- Do not extract a single string or number into a module-level constant; inline it.
+- Prefer `NamedTuple` with named fields over bare tuples that are indexed.
+- `from __future__ import annotations` in every module; imports used only in annotations go under
+  `if TYPE_CHECKING:`.
+- Line length is 120, ruff formats and lints, `ty` type-checks. Fix the code, not the config.

langfuse_hotswap-0.1.0/.claude/rules/runnable.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "src/langfuse_hotswap/_runnable.py"
+---
+
+# The runnable
+
+- Every `Runnable` method resolves the chain once (`_prepare` or `_aprepare`) and delegates to it.
+  A batch method fetches the prompt once for all inputs.
+- `_built` and `_failed` are replaced as whole `NamedTuple`s, never mutated, so readers outside the
+  lock see a consistent pair.
+- Rebuilds run under `_lock`. Without a built chain callers wait for the build; with one, a call
+  that finds the lock taken is served by the previous chain.
+- A failed build is cached for a minute in `_failed`; a failed fetch is logged at most once a
+  minute. Both keep serving the previous chain.
+- Async: fetch on the event loop only when `_cache_is_warm()` is true; otherwise, and for every
+  rebuild, go through `run_in_executor`. Never call a blocking fetch or build directly in an
+  `async def`.
+- Hooks and the template metadata get a deep copy of the prompt; the original is kept only for
+  comparison. Compare prompts by identity first, then by content.
+- Errors leaving the runnable are `PromptFetchError` or `ChainBuildError` with the original as
+  `__cause__`.

langfuse_hotswap-0.1.0/.claude/rules/tests.md

@@ -0,0 +1,22 @@
+---
+paths:
+  - "tests/**/*.py"
+---
+
+# Tests
+
+- One test module per source module: `test_config.py`, `test_runnable.py`, `test_template.py`,
+  `test_factory.py`. Inside a module, group tests under `# Section` comments.
+- Every test has a docstring with one sentence that states the behavior under test, in the
+  present tense: "A version that fails to build is served by the previous chain and logged once."
+  Not "Tests that…", not the implementation.
+- The test name and the docstring describe the same behavior; rename the test when it changes.
+- Arrange, act and assert are separated by blank lines.
+- Use the fixtures from `conftest.py`: `client` (fake Langfuse), `init_calls` (records the
+  `init_chat_model` arguments and returns `FakeChatModel`), `factory` (allowlist disabled).
+- Shared doubles live in `fakes.py`. Do not add network calls or real providers.
+- Time-dependent behavior (the one-minute windows) is tested by patching
+  `langfuse_hotswap._runnable.time.monotonic`, not by sleeping.
+- Concurrency tests may slow a hook down with a short `time.sleep` so that concurrent calls
+  overlap. Use `threading.Event` with a timeout when the test needs an exact interleaving.
+- A security rule (blocked keys, provider selection, precedence) gets a test that tries to break it.

langfuse_hotswap-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run ty check
+      - run: uv run pytest -q

langfuse_hotswap-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,42 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  # Runs the tests and builds the package without publishing rights, so code from the dev
+  # dependencies never sees the PyPI token.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+      - run: uv sync --locked
+      - run: uv run pytest -q
+      - run: uv build
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
+        with:
+          name: dist
+          path: dist/
+      - uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5.4.2
+      - run: uv publish --trusted-publishing always dist/*

langfuse_hotswap-0.1.0/.gitignore

@@ -0,0 +1,23 @@
+# Mac OS
+.DS_Store
+
+# JetBrains
+.idea
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+
+# Distribution / packaging
+src/langfuse_hotswap/_version.py
+build/
+dist/
+*.egg-info/
+
+# Environments and secrets
+.venv/
+.env
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/

langfuse_hotswap-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

langfuse_hotswap-0.1.0/CLAUDE.md

@@ -0,0 +1,48 @@
+# langfuse-hotswap
+
+A LangChain `Runnable` whose chat model and its parameters live in the Langfuse prompt config.
+Every call fetches the prompt through the Langfuse SDK cache and delegates to `template | model`
+built for it; the chain is rebuilt when the prompt changes.
+
+## Commands
+
+```shell
+uv sync                                   # install with the dev group
+uv run pytest -q                          # tests
+uv run ruff format . && uv run ruff check . && uv run ty check
+```
+
+Run all four before reporting a change as done. CI runs the same on Python 3.11–3.13.
+
+## Layout
+
+| Path | What lives there |
+|---|---|
+| `src/langfuse_hotswap/_config.py` | `build_model_params`: allowlist, blocked keys, explicit provider, precedence of kwargs |
+| `src/langfuse_hotswap/_runnable.py` | `LangfusePromptRunnable`: fetch, compare, rebuild under a lock, async fast path, hooks |
+| `src/langfuse_hotswap/_template.py` | `LangfusePromptTemplate`: rendering with the Langfuse `TemplateParser` |
+| `src/langfuse_hotswap/_factory.py` | `LangfuseChainFactory`: shared client and kwargs, `create` arguments |
+| `src/langfuse_hotswap/_errors.py` | `HotswapError`, `PromptFetchError`, `ChainBuildError` |
+| `tests/fakes.py`, `tests/conftest.py` | fake Langfuse client, fake chat model, `init_calls` fixture |
+| `tests/test_<module>.py` | one test module per source module |
+
+The public API is what `src/langfuse_hotswap/__init__.py` imports. Modules are private (`_name.py`).
+
+## Invariants
+
+- Code beats config: precedence is prompt config < factory kwargs < provider kwargs.
+- The provider comes only from an explicit `model_provider`; it is never inferred from the model name.
+- Blocked config keys (`is_blocked_config_key`) never reach the model, whatever the allowlist says.
+- A broken prompt never takes down a working chain: the previous chain keeps serving.
+- The async path never blocks the event loop on HTTP when the SDK cache is cold.
+
+Behavior changes go together with tests and the README.
+
+## Conventions
+
+Path-scoped rules in `.claude/rules/` load when matching files are touched: Python style, tests,
+the config and runnable modules, README and CI. The short version:
+
+- Docstrings say what, not why, and are always multi-line.
+- No `__all__`, no module-level constants for single literals.
+- Never commit or create branches unless asked.

langfuse_hotswap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ruslan Glotov
+
+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.