khazad 0.1.2__tar.gz

khazad-0.1.2/.gitignore

@@ -0,0 +1,207 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

khazad-0.1.2/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.2] - 2026-06-29
+
+### Added
+
+- `examples` dependency group in `pyproject.toml` (`OpenAI`, `Anthropic`, `google-genai`, `azure-identity`) so the provider example scripts run with `uv run --group examples`.
+- Extended and expanded the per-provider example scripts.
+
+### Changed
+
+- README images now use absolute `raw.githubusercontent.com` URLs so they render on the PyPI project page.
+
+## [0.1.1] - 2026-06-24
+
+### Changed
+
+- Replaced the `shared_models` parameter with `cache_scope` (a `CacheScope` enum — `MODEL` by default, `HOST` to opt in) to control cache partitioning.
+- Rewrote the README and added a flow diagram illustrating the request lifecycle.
+
+### Added
+
+- Standalone example scripts for each supported provider, including streaming usage.
+
+### Fixed
+
+- Streaming cache misses are now correctly tee'd, reconstructed into canonical JSON at stream end, and cached.
+
+## [0.1.0] - 2026-06-13
+
+First public release.
+
+### Added
+
+- Transparent semantic cache for LLM API calls via `httpx` transport patching — zero changes to application code.
+- Module-level singleton API (`khazad.init()` / `stop()` / `get_stats()` / `flush()` / `is_active()`) and explicit `Khazad` class with the same surface.
+- Redis 8 Vector Sets backend (`VADD` / `VSIM`), one vector set per `(provider host, model)` scope so different models never cross-serve.
+- Provider parsers: OpenAI Chat Completions (incl. Azure OpenAI and any OpenAI-compatible proxy), OpenAI Responses API, Anthropic Messages, Google Gemini `generateContent`.
+- Conversation-aware matching: the full message list (system, user, assistant) is embedded, not just the last user turn.
+- Streaming support both ways:
+  - cache hits replay as SSE streams for sync and async clients;
+  - streaming cache misses are tee'd to the client with no added latency, reconstructed into canonical JSON at stream end, and cached (aborted streams are never cached).
+- Embedding backends: HuggingFace `sentence-transformers` (default, local) and OpenAI Embeddings (optional extra `khazad[openai-embeddings]`).
+- Configurable similarity threshold, TTL with automatic pruning of orphaned vectors, Redis key namespace, log level.
+- Thread-safe hit/miss statistics (`total_requests`, `cache_hits`, `cache_misses`, `hit_rate`, `avg_hit_similarity`).
+- `hosts` opt-in allowlist (exact hosts and `*.` wildcard subdomains) — restricts interception to explicitly listed endpoints.
+
+[0.1.2]: https://github.com/GuglielmoCerri/khazad/releases/tag/v0.1.2
+[0.1.1]: https://github.com/GuglielmoCerri/khazad/releases/tag/v0.1.1
+[0.1.0]: https://github.com/GuglielmoCerri/khazad/releases/tag/v0.1.0

khazad-0.1.2/CLAUDE.md

@@ -0,0 +1,255 @@
+# CLAUDE.md - Khazad Project Context
+
+## Frequently Used Commands
+
+```bash
+# Setup
+uv sync --group dev        # Install all dependencies (creates .venv automatically)
+
+# Testing (no Redis or API keys needed — fakes and mock transports)
+uv run python -m pytest tests/ -q                              # Full suite
+uv run python -m pytest tests/unit/ -q                         # Unit tests only
+uv run python -m pytest -m "not stress"                        # Skip stress tests
+
+# Lint / format
+uv run python -m ruff check . --fix    # Lint with auto-fix
+uv run python -m ruff format .         # Format code
+
+# Quick smoke test (requires Redis 8 + endpoint credentials)
+uv run --group examples python -P examples/azure_openai.py
+```
+
+## Important Architectural Patterns
+
+### Single Entry Point — `Khazad` Class
+
+Everything goes through one class. There is no separate engine, config model, or orchestrator.
+`Khazad` owns the embedder, vector store, parsers, stats, and cache logic directly.
+
+```python
+from khazad import Khazad
+
+cache = Khazad(redis_url="redis://localhost:6379", threshold=0.92)
+# ... all LLM HTTP traffic is now cached ...
+cache.stop()
+```
+
+A module-level singleton API (`khazad.init()` / `khazad.stop()`) wraps `Khazad` for convenience.
+
+### Request lifecycle: prepare → lookup → store
+
+The transport calls `Khazad.prepare(request)` exactly once per request. It returns a
+`PreparedRequest` (parser, prompt, scope, stream flag) or `None` for pass-through.
+The request body is JSON-parsed **once**; the embedding is computed lazily and memoized
+on the `PreparedRequest`, so a miss that later stores its response never re-embeds.
+
+- `prepare(request) -> PreparedRequest | None` — parser matching + body parsing
+- `lookup(prepared) -> CacheHit | None` — embed, VSIM search, stats
+- `store(prepared, response_bytes)` — reuses the memoized embedding
+
+`prepare()` also applies the opt-in `hosts=[...]` allowlist (exact match or `*.suffix`
+wildcard, case-insensitive) — non-allowed hosts pass through untouched.
+
+A temperature-based gate (`cache_only_deterministic`) was evaluated and deliberately
+**rejected**: GPT-5-family and o-series models hard-reject any `temperature` other than
+the default 1.0 (400 error), so gating on `temperature=0` would make flagship models
+permanently uncacheable. Do not reintroduce it.
+
+Unparseable, unmatched, or non-allowlisted requests are **not counted** in stats.
+
+### Cache scope: host + model
+
+`scope = f"{host}/{model or 'default'}"`. Each scope gets its own Redis vector set,
+so the same prompt sent to `gpt-4o` and `gpt-4o-mini` can never cross-serve.
+The prompt text embedded is the **full conversation** (`role: text` lines, including
+system), not just the last user message — prevents multi-turn collisions.
+
+The opt-in `cache_scope` parameter (a `CacheScope` enum — `MODEL` by default, `HOST`
+to opt in; keyword-only on `Khazad`, also on `khazad.init`) controls this. Pass
+`cache_scope=CacheScope.HOST` (or the string `"host"`) to collapse the scope to `host`
+only, so every model/deployment on the same provider shares one vector set. The host
+always stays in the scope, so different providers (Azure OpenAI vs Gemini) remain
+isolated and a response is never replayed to a client expecting a different wire
+format. Use it only for format-compatible pools (e.g. several Azure OpenAI
+deployments, or `gpt-4o` + `gpt-4o-mini`).
+
+### Hexagonal Architecture (Ports & Adapters)
+
+- **Ports** (`khazad/ports/`) — abstract interfaces: `Embedder`, `ProviderParser`, `VectorStore`
+- **Adapters** (`khazad/adapters/`) — concrete implementations (Redis, HuggingFace, OpenAI, parsers)
+- `ProviderParser` is an ABC with shared concrete helpers (`build_response`, `_sse`,
+  `_iter_sse_payloads`, `_flatten_text`) — subclasses implement `can_handle` and
+  `parse_request`, and optionally override `stream_chunks` / `response_from_stream`.
+- There is **no Azure parser** — Azure OpenAI is covered by `OpenAIParser`'s
+  path-suffix matching (`/chat/completions`).
+
+### httpx Transport Monkey-Patching
+
+Khazad intercepts LLM traffic by patching `httpx.Client.__init__` and `httpx.AsyncClient.__init__`
+to wrap their transports (`khazad/_transport.py`, `install(cache)` / `uninstall()`).
+
+`install()` is **idempotent for the original-init capture**: only the first call records the
+pristine `httpx.*Client.__init__` references. Subsequent calls swap the active cache without
+overwriting the originals, so `uninstall()` always restores real httpx.
+
+Transports check `cache.is_active()` on every request — clients created while the patch
+was installed stop serving from cache immediately after `stop()`.
+
+### Streaming
+
+- **Hit**: `parser.stream_chunks(cached_json)` is a *sync* generator of SSE frames;
+  `_ReplayStream` implements both `SyncByteStream` and `AsyncByteStream`, so sync and
+  async clients both replay correctly.
+- **Miss**: the upstream SSE body is tee'd through `_SyncTeeStream` / `_AsyncTeeStream`
+  with zero added latency. The collected bytes are passed to `parser.response_from_stream(sse)`
+  when the stream ends — on natural exhaustion **or** on `close()`/`aclose()`. The latter
+  matters because SDKs (e.g. the OpenAI client) break their read loop on the terminal SSE
+  sentinel and close the response without driving the byte stream to EOF, so caching on
+  natural exhaustion alone would never fire. `response_from_stream` reconstructs the
+  **canonical JSON response** only when the capture is complete (OpenAI Chat requires the
+  `[DONE]` sentinel, Anthropic requires `message_stop`, Responses requires
+  `response.completed`); a partial/aborted stream reconstructs to `None` and is never cached.
+- Compressed SSE bodies (`content-encoding != identity`) are passed through uncached.
+- Gemini streaming (`:streamGenerateContent`) is not matched at all — pass-through.
+
+### Redis adapter (`khazad/adapters/redis/store.py`)
+
+- One vector set per scope: `{namespace}:vset:{scope}`; bodies at `{namespace}:resp:{key}`.
+- `store()` pipelines `VADD` + `SET ex=ttl` (single round-trip).
+- VSIM workaround: redis-py's `parse_vsim_result` callback misparses RESP3 dict responses
+  when the WITHSCORES option flag isn't propagated (found in 8.0.0b2, callback unchanged
+  in 8.0.0 GA — dependency is now `redis>=8.0.0,<9`). `search()` issues a raw
+  `execute_command("VSIM", ...)` and `_parse_vsim_response` handles both RESP3 dict and
+  RESP2 flat-list shapes.
+- TTL: only the response body expires. `Khazad.lookup` prunes the orphaned vector
+  (`store.delete(scope, key)`) when the body is gone, then counts a miss.
+
+### Testing with Dependency Injection
+
+For tests, `Khazad` accepts `_vector_store` and `_embedder_instance` keyword args (both or
+neither) to bypass Redis and real embedding models:
+
+```python
+cache = Khazad(
+    threshold=0.99,
+    _vector_store=InMemoryVectorStore(),
+    _embedder_instance=FakeEmbedder(),
+)
+```
+
+This skips Redis connection and transport patching entirely (tests call
+`install(cache)` / `uninstall()` themselves).
+
+## Critical Rules
+
+### Git Operations
+
+**CRITICAL**: NEVER use `git push` or attempt to push to remote repositories. The user will handle all git push operations.
+
+### Code Quality
+
+**IMPORTANT**: Always run `uv run python -m ruff check . --fix && uv run python -m ruff format .` before committing.
+
+### README.md Maintenance
+
+**IMPORTANT**: DO NOT modify README.md unless explicitly requested.
+
+### No Pydantic
+
+The project deliberately removed `pydantic` as a dependency. Validation is done inline in `Khazad.__init__`.
+Do not reintroduce pydantic.
+
+### No Separate Engine Class
+
+All cache logic (lookup, store, stats, key generation) lives in the `Khazad` class.
+Do not create a separate `CacheEngine` or orchestrator class.
+
+### Python 3.10 Compatibility
+
+`requires-python = ">=3.10"` (ruff target py310). No 3.11+ stdlib APIs (`tomllib`,
+`StrEnum`, `asyncio.timeout`, exception groups). Every module starts with
+`from __future__ import annotations`. Dev venv is pinned to 3.13 via `.python-version`.
+
+## Testing Notes
+
+- **Unit tests** use `FakeEmbedder` and `InMemoryVectorStore` from `tests/conftest.py` — no external services needed
+- **Integration tests** use `httpx.MockTransport` to simulate LLM APIs — no real API keys needed
+- **Redis store tests** (`test_redis_store.py`) mock the redis-py client with plain `Mock`/`MagicMock` (the store is sync — never use `AsyncMock` there)
+- **Stress tests** are marked with `@pytest.mark.stress`
+- `pytest-asyncio` runs in auto mode (`asyncio_mode = "auto"`)
+- `conftest.py` provides fixtures for all provider request/response bodies
+- `FakeEmbedder` hashes with sha256 (deterministic across processes — `hash()` is salted)
+
+## Project Structure
+
+```text
+khazad/
+├── __init__.py           # Public API + module-level singleton (init/stop/get_stats/flush)
+├── khazad.py             # Khazad class + PreparedRequest — all cache logic
+├── _models.py            # Domain models: ParsedRequest, CacheHit, Stats
+├── _transport.py         # httpx patch, cached transports, tee/replay streams
+├── ports/                # Abstract interfaces (Hexagonal Architecture boundaries)
+│   ├── embedder.py       # Embedder ABC (embed, dimension)
+│   ├── parser.py         # ProviderParser ABC + shared SSE/text helpers
+│   └── store.py          # VectorStore ABC (scope-aware search/store/delete)
+└── adapters/             # Concrete implementations
+    ├── embedders/
+    │   ├── huggingface.py    # HuggingFaceEmbedder (sentence-transformers, free)
+    │   └── openai.py         # OpenAIEmbedder (OpenAI API, paid)
+    ├── parsers/
+    │   ├── openai.py             # OpenAI Chat Completions (+ Azure, proxies)
+    │   ├── openai_responses.py   # OpenAI Responses API
+    │   ├── anthropic.py          # Anthropic Messages
+    │   └── gemini.py             # Google Gemini
+    └── redis/
+        └── store.py          # RedisVectorStore (Redis 8 Vector Sets)
+
+tests/
+├── conftest.py           # FakeEmbedder, InMemoryVectorStore, provider fixtures
+├── unit/                 # Pure logic tests (no I/O)
+│   ├── test_config.py    # Khazad init validation
+│   ├── test_engine.py    # prepare/lookup/store, scoping, stats, embedding reuse
+│   ├── test_models.py    # Stats, CacheHit
+│   └── test_parsers/     # Per-provider parser tests (incl. SSE round-trips)
+├── integration/          # Full lifecycle with mock transports
+│   ├── test_end_to_end.py
+│   ├── test_interceptor.py
+│   ├── test_redis_store.py              # Mocked redis-py client
+│   ├── test_streaming.py                # SSE capture + replay, sync & async
+│   ├── test_provider_openai.py          # OpenAI Chat + Responses
+│   ├── test_provider_azure_openai.py    # Azure deployments
+│   ├── test_provider_openai_compat.py   # LiteLLM, vLLM, Ollama
+│   ├── test_provider_anthropic.py       # Anthropic Claude
+│   └── test_provider_gemini.py          # Google Gemini
+└── stress/               # Concurrent access, thread safety
+    └── test_concurrent.py
+
+examples/
+└── azure_openai.py       # Smoke test against a real endpoint
+
+docs/
+└── _static/              # Logos (logo-light.png / logo-dark.png are transparent)
+```
+
+## Supported Providers
+
+| Provider | Parser | URL pattern matched |
+|---|---|---|
+| OpenAI Chat | `OpenAIParser` | any path ending `/chat/completions` |
+| OpenAI Responses | `OpenAIResponsesParser` | any path ending `/responses` |
+| Azure OpenAI | (covered by `OpenAIParser`) | any path ending `/chat/completions` |
+| OpenAI-compat proxies | (covered by `OpenAIParser`) | any path ending `/chat/completions` |
+| Anthropic | `AnthropicParser` | `api.anthropic.com/v1/messages` |
+| Google Gemini | `GeminiParser` | `generativelanguage.googleapis.com/*:generateContent` |
+
+## Cache Flow
+
+```text
+Request → prepare(request)
+  None → pass-through to real API (not counted in stats)
+  PreparedRequest → embed(conversation) → VSIM in scope {host}/{model}
+      HIT  → replay cached JSON (or synthesize SSE stream)
+      MISS → forward to API
+             non-streaming 200 → store JSON body
+             SSE 200 → tee stream to client, reconstruct JSON at end, store
+```

khazad-0.1.2/CONTRIBUTING.md

@@ -0,0 +1,81 @@
+# Contributing to Khazad
+
+Thanks for considering a contribution! This document covers everything you need to get a change merged.
+
+## Development setup
+
+Requirements: Python >= 3.10 and [uv](https://docs.astral.sh/uv/).
+
+```bash
+git clone https://github.com/GuglielmoCerri/khazad.git
+cd khazad
+uv sync --group dev
+```
+
+`uv sync` creates `.venv` and installs the project in editable mode — nothing else to do.
+
+A running Redis is **not** required for the test suite (fakes and mock transports are used everywhere). For manual end-to-end testing against a real instance:
+
+```bash
+docker run -d --name redis8 -p 6379:6379 redis:8
+```
+
+## Running tests
+
+```bash
+uv run python -m pytest tests/ -q          # full suite
+uv run python -m pytest tests/unit/ -q     # unit tests only
+uv run python -m pytest -m "not stress"    # skip stress tests
+```
+
+The suite must be green before any PR. New behavior needs new tests:
+
+- **Parsers** → `tests/unit/test_parsers/` (include an SSE round-trip test if the parser supports streaming: `stream_chunks` → `response_from_stream` must preserve content)
+- **Cache logic** → `tests/unit/test_engine.py`
+- **Transport / interception** → `tests/integration/`
+
+## Lint and format
+
+```bash
+uv run python -m ruff check . --fix
+uv run python -m ruff format .
+```
+
+CI rejects unformatted code. Configuration lives in `pyproject.toml` (line length 99, target py310).
+
+## Architecture ground rules
+
+Read `CLAUDE.md` for the full picture. The non-negotiables:
+
+1. **One entry point.** All cache logic lives in the `Khazad` class — do not introduce a separate engine, orchestrator, or config object.
+2. **No pydantic.** Validation is inline in `Khazad.__init__`. Plain dataclasses for models.
+3. **Ports & Adapters.** New providers implement `ProviderParser` (`khazad/ports/parser.py`); new storage backends implement `VectorStore`; new embedders implement `Embedder`. Adapters never import other adapters.
+4. **Parse once.** A request body is JSON-parsed exactly once (`parse_request`); the embedding is computed at most once per request. Don't add code paths that re-parse or re-embed.
+5. **The cache stores canonical JSON only.** Streamed responses must be reconstructed via `response_from_stream` before storing — never cache raw SSE bytes.
+6. **Python 3.10 compatibility.** No 3.11+ stdlib APIs (`tomllib`, `StrEnum`, `asyncio.timeout`, exception groups...). Use `from __future__ import annotations` in every module.
+
+## Adding a new provider parser
+
+1. Create `khazad/adapters/parsers/<provider>.py` implementing `ProviderParser`:
+   - `can_handle(url)` — match by URL path suffix when the API is host-agnostic (proxies!), by host only when the schema is unique to one vendor.
+   - `parse_request(request)` — return a `ParsedRequest(prompt, model, stream)`. The prompt must include the **full conversation** (`role: text` lines), and raise `ValueError` for bodies you can't understand.
+   - Override `stream_chunks` / `response_from_stream` only if the provider streams over SSE.
+2. Register it in the `_parsers` list in `khazad/khazad.py`.
+3. Add request/response fixtures in `tests/conftest.py`, unit tests in `tests/unit/test_parsers/`, and an interception test in `tests/integration/`.
+4. Document the URL pattern in the README "Supported Providers" table.
+
+## Pull requests
+
+- Branch from `main`; one logical change per PR.
+- Subject line in imperative mood ("Add Mistral parser", not "Added...").
+- Explain *why* in the body if it isn't obvious from the diff.
+- Update `CHANGELOG.md` under `[Unreleased]`.
+- Don't bump the version — maintainers handle releases.
+
+## Reporting bugs
+
+Open an issue with: Python version, khazad version, the SDK and provider you're calling, a minimal reproduction, and (if relevant) `log_level="DEBUG"` output. For suspected cache-correctness issues, include the two prompts involved and your `threshold`.
+
+## Security
+
+Don't open public issues for security problems — see the contact in `pyproject.toml`.

khazad-0.1.2/LICENSE

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