omg-llmkit 0.1.0__tar.gz

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

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        run: uv python install 3.13
+
+      - name: Install dependencies
+        run: uv sync --extra dev
+
+      - name: Ruff (lint)
+        run: uv run ruff check .
+
+      - name: Ruff (format check)
+        run: uv run ruff format --check .
+
+      - name: basedpyright (no baseline)
+        run: uv run basedpyright
+
+      - name: Tests
+        run: uv run pytest

omg_llmkit-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,49 @@
+name: Publish to PyPI
+
+# Publishes to PyPI when a GitHub Release is published. Uses PyPI Trusted
+# Publishing (OIDC) — there is NO API token stored in the repo. Configure the
+# matching "pending publisher" on PyPI first (see CONTRIBUTING / release notes):
+#   project: omg-llmkit | owner: OMGBrews | repo: llmkit
+#   workflow: publish.yml | environment: pypi
+# (PyPI distribution name is "omg-llmkit"; the import name stays "llmkit".)
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Build sdist and wheel
+        run: uv build
+
+      - name: Upload dist artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/omg-llmkit
+    permissions:
+      id-token: write    # required for PyPI Trusted Publishing (OIDC)
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

omg_llmkit-0.1.0/.gitignore

@@ -0,0 +1,16 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+
+# Virtual env / uv
+.venv/
+uv.lock
+
+# Local LLM call logs (default LocalYamlLogSink output)
+data/llm-logs/
+
+# Editor / OS
+.DS_Store

omg_llmkit-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[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.0] — 2026-06-05
+
+Initial public release.
+
+### Added
+
+- Provider-agnostic call surface over LiteLLM (with `instructor` for structured
+  output) across OpenRouter, Google, Anthropic, and local Ollama.
+- `structured_llm_call` / `structured_llm_call_sync` — validated Pydantic output,
+  with each provider pinned to its native JSON-schema mode (never auto-`Mode.TOOLS`).
+- `text_llm_call` and `stream_text_with_log` for plain-text and streamed calls.
+- Process-global async rate limiter (`GlobalRateLimiter`, `configure_rate_limit`).
+- Transient-error retries (`with_retries`, `LLM_RECOVERABLE_ERRORS`), kept
+  separate from instructor's schema-repair retries.
+- Agent-readable logging: `LocalYamlLogSink` writes verdict-first per-call YAML
+  plus an append-only `index.jsonl`; pluggable `LogSink` protocol for custom sinks.
+- Approximate per-call cost (`approximate_cost`) sourced from LiteLLM's response
+  estimate, for budget visibility.
+
+[0.1.0]: https://github.com/OMGBrews/llmkit/releases/tag/v0.1.0

omg_llmkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,32 @@
+# Contributing
+
+Thanks for your interest. This is a small, opinionated, best-effort project — see
+the scope notes in the [README](README.md). Bug reports and focused pull requests
+are welcome; large feature proposals may not be a fit for the library's
+deliberately-thin design, so please open an issue to discuss before investing in
+a big change.
+
+## Development setup
+
+```bash
+uv sync --extra dev
+```
+
+## Checks must pass
+
+CI runs the same four gates on every push and pull request, with **no baseline**:
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+uv run basedpyright          # 0 errors, 0 warnings
+uv run pytest
+```
+
+Please run them locally before opening a PR. New behavior needs a test.
+
+## Conventions
+
+- Keep the public surface small — `llmkit` owns the call ergonomics, not transport.
+- No `dict[str, Any]` / bare `Any`; use precise types (basedpyright enforces this).
+- Hard cuts over deprecation shims for internal changes.

omg_llmkit-0.1.0/LICENSE

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

omg_llmkit-0.1.0/PKG-INFO

@@ -0,0 +1,226 @@
+Metadata-Version: 2.4
+Name: omg-llmkit
+Version: 0.1.0
+Summary: A thin, opinionated, local-first structured-output + logging layer over LiteLLM
+Project-URL: Homepage, https://github.com/OMGBrews/llmkit
+Project-URL: Repository, https://github.com/OMGBrews/llmkit
+Project-URL: Issues, https://github.com/OMGBrews/llmkit/issues
+Project-URL: Changelog, https://github.com/OMGBrews/llmkit/blob/main/CHANGELOG.md
+Author: OMGBrews
+License: MIT License
+        
+        Copyright (c) 2026 OMGBrews
+        
+        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.
+License-File: LICENSE
+Keywords: anthropic,gemini,instructor,litellm,llm,openai,structured-output
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: instructor>=1.15.1
+Requires-Dist: litellm>=1.87.1
+Requires-Dist: openai>=2.0.0
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0.0
+Provides-Extra: dev
+Requires-Dist: basedpyright>=1.39; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff==0.15.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# llmkit
+
+A thin, opinionated, **local-first** layer over [LiteLLM](https://github.com/BerriAI/litellm) (with [instructor](https://github.com/567-labs/instructor) for structured output). It gives an application one provider-agnostic call surface across **OpenRouter, Google, Anthropic, and local Ollama**, with validated structured output, a global async rate limiter, transient-error retries, and **agent-readable per-call logging** out of the box.
+
+LiteLLM is the implementation of the HTTP providers; llmkit owns the ergonomic call surface, the structured-output mode pinning, the rate-limit policy, and the logging convention. It is **not** a gateway and does not reimplement transport — that is solved, and reimplementing it is the thing this library deliberately does not do.
+
+## Why llmkit
+
+- **Structured output that actually validates.** Each provider is pinned to its *native* JSON-schema mode (never instructor's auto-`Mode.TOOLS`, which silently regresses Gemini to empty shapes), and instructor's in-call validation-retry repairs truncated JSON. You pass a Pydantic model; you get a validated instance back.
+- **Provider switching is config, not code.** OpenRouter / Google / Anthropic / Ollama behind one `Provider` enum and one `LLMClientConfig`. Call sites never change when you switch.
+- **Logging tuned for coding agents.** Every call is logged verdict-first (see below) — the design assumption is that the reader is usually an LLM coding agent debugging a run, not a dashboard.
+- **Local-first, zero infra.** The default sink writes plain files to a directory. No collector, no account, no network. A pluggable `LogSink` lets you ship records anywhere later without touching call sites.
+
+## Install
+
+```bash
+uv add omg-llmkit          # or: pip install omg-llmkit
+```
+
+The distribution is published as **`omg-llmkit`** (the bare `llmkit` name was already
+taken on PyPI), but the import name is just `llmkit`:
+
+```python
+import llmkit
+```
+
+Requires Python ≥ 3.13.
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+from llmkit import (
+    LLMClientConfig,
+    Provider,
+    configure_llm_client,
+    structured_llm_call,
+)
+
+# Point the library at a provider once, at startup.
+configure_llm_client(lambda: LLMClientConfig(
+    provider=Provider.OPENROUTER,
+    model="google/gemini-2.5-flash",
+    api_key="sk-or-...",
+))
+
+class Summary(BaseModel):
+    title: str
+    bullets: list[str]
+
+result: Summary = await structured_llm_call(
+    prompt="Summarize the attached report.",
+    schema=Summary,
+    feature="reports",      # groups calls in the logs
+    label="exec_summary",   # names this specific call in the logs
+)
+```
+
+The public call surface:
+
+| Function | Use |
+|----------|-----|
+| `structured_llm_call(prompt, schema, feature, label, ...)` | Async, returns a validated Pydantic instance |
+| `structured_llm_call_sync(...)` | Synchronous wrapper around the above |
+| `text_llm_call(prompt, feature, label, ...)` | Async, returns plain text (coerces provider list-content blocks) |
+| `stream_text_with_log(prompt, feature, label, ...)` | Async generator yielding text chunks, logged on completion |
+
+`configure_rate_limit(...)` sets the process-global concurrency cap; `configure_llm_logging(sink)` swaps the log sink (below).
+
+## Logging: agent-readable by default
+
+`LocalYamlLogSink` (the default) writes **two** things to `data/llm-logs/`:
+
+1. **One YAML file per call, laid out verdict-first.** The file opens with a one-line `#` header — `ok`/`ERROR`, feature/label, resolved model, schema, duration, approximate cost — so `head -1 *.yaml` triages a whole run. Small metadata is next; the large `response` and `prompt` blobs are last, so the *head* of the file is the whole story for most reads.
+2. **A compact append-only `index.jsonl`** — one JSON line per call (file, timestamp, feature, label, model, provider, schema, duration, cost, error). Cross-call questions — "which calls errored / were slowest / most expensive / the last call for feature X" — are a single small scan instead of globbing and parsing every YAML.
+
+```
+# ok | reports/exec_summary | google/gemini-2.5-flash | Summary | 1840ms | $0.0007
+# 2026-06-05T14:22:31.004512
+
+timestamp: '2026-06-05T14:22:31.004512'
+feature: reports
+label: exec_summary
+model: google/gemini-2.5-flash
+provider: openrouter
+schema: Summary
+temperature: 0.0
+duration_ms: 1840.2
+approximate_cost: 0.0007
+error: null
+response: ...
+prompt: ...
+```
+
+`approximate_cost` is LiteLLM's per-response estimate for budget visibility — **not** a billing figure (and `None` when the provider does not report it, e.g. streamed calls).
+
+### Write your own `LogSink`
+
+`LogSink` is a one-method `Protocol`. Records (`LLMCallRecord`, a frozen dataclass) are handed to your sink for every call; failures are swallowed so logging can never break a call. To send records somewhere other than local YAML — a database, an HTTP collector, structured stdout — implement `write` and register it:
+
+```python
+import logging
+from pathlib import Path
+from llmkit import LLMCallRecord, configure_llm_logging
+
+logger = logging.getLogger("llm-calls")
+
+class StructuredStdoutSink:
+    def write(self, record: LLMCallRecord) -> Path | None:
+        logger.info(
+            "llm_call",
+            extra={
+                "feature": record.feature,
+                "label": record.label,
+                "model": record.model,
+                "provider": record.provider,
+                "schema": record.schema,
+                "duration_ms": record.duration_ms,
+                "approximate_cost": record.approximate_cost,
+                "error": record.error,
+            },
+        )
+        return None  # nothing persisted to a path
+
+configure_llm_logging(StructuredStdoutSink())   # pass None to disable logging entirely
+```
+
+An OpenTelemetry exporter (e.g. to Langfuse/Phoenix) is a natural future `llmkit[otel]` extra; the pluggable seam makes it a non-breaking addition.
+
+## Configuration
+
+`LLMClientConfig` is flat and carries only what a call needs:
+
+```python
+@dataclass(frozen=True)
+class LLMClientConfig:
+    provider: Provider          # OPENROUTER | OLLAMA | GOOGLE | ANTHROPIC
+    model: str                  # the provider's default model
+    api_key: str | None = None
+    base_url: str | None = None
+```
+
+Per-call `model=` overrides the default, so "strong/small/current" model roles are the host's concern — resolve them to a model string and pass it at the call site. The library has no opinion about roles.
+
+Register the config with `configure_llm_client(source)`, where `source` is a zero-arg callable returning an `LLMClientConfig` (re-read on each provider construction, so it tracks live settings changes).
+
+## Retries
+
+Two retry layers, kept deliberately separate:
+
+- **`with_retries()`** ([`retry.py`](src/llmkit/retry.py)) handles *transient provider* errors (429 / 503 / 5xx; the recoverable set is `LLM_RECOVERABLE_ERRORS`).
+- **instructor's own low `max_retries`** handles *schema-validation* repair (re-ask the model to fix malformed JSON).
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check . && uv run ruff format --check .
+uv run basedpyright          # 0 errors, 0 warnings — no baseline
+uv run pytest
+```
+
+## Status & support
+
+`llmkit` is a small, opinionated, **best-effort** project, extracted from a real
+application and maintained in the open. It is used in production by its author
+but carries no support SLA. Bug reports and focused pull requests are welcome —
+see [CONTRIBUTING.md](CONTRIBUTING.md). For security issues, see
+[SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

omg_llmkit-0.1.0/README.md

@@ -0,0 +1,173 @@
+# llmkit
+
+A thin, opinionated, **local-first** layer over [LiteLLM](https://github.com/BerriAI/litellm) (with [instructor](https://github.com/567-labs/instructor) for structured output). It gives an application one provider-agnostic call surface across **OpenRouter, Google, Anthropic, and local Ollama**, with validated structured output, a global async rate limiter, transient-error retries, and **agent-readable per-call logging** out of the box.
+
+LiteLLM is the implementation of the HTTP providers; llmkit owns the ergonomic call surface, the structured-output mode pinning, the rate-limit policy, and the logging convention. It is **not** a gateway and does not reimplement transport — that is solved, and reimplementing it is the thing this library deliberately does not do.
+
+## Why llmkit
+
+- **Structured output that actually validates.** Each provider is pinned to its *native* JSON-schema mode (never instructor's auto-`Mode.TOOLS`, which silently regresses Gemini to empty shapes), and instructor's in-call validation-retry repairs truncated JSON. You pass a Pydantic model; you get a validated instance back.
+- **Provider switching is config, not code.** OpenRouter / Google / Anthropic / Ollama behind one `Provider` enum and one `LLMClientConfig`. Call sites never change when you switch.
+- **Logging tuned for coding agents.** Every call is logged verdict-first (see below) — the design assumption is that the reader is usually an LLM coding agent debugging a run, not a dashboard.
+- **Local-first, zero infra.** The default sink writes plain files to a directory. No collector, no account, no network. A pluggable `LogSink` lets you ship records anywhere later without touching call sites.
+
+## Install
+
+```bash
+uv add omg-llmkit          # or: pip install omg-llmkit
+```
+
+The distribution is published as **`omg-llmkit`** (the bare `llmkit` name was already
+taken on PyPI), but the import name is just `llmkit`:
+
+```python
+import llmkit
+```
+
+Requires Python ≥ 3.13.
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+from llmkit import (
+    LLMClientConfig,
+    Provider,
+    configure_llm_client,
+    structured_llm_call,
+)
+
+# Point the library at a provider once, at startup.
+configure_llm_client(lambda: LLMClientConfig(
+    provider=Provider.OPENROUTER,
+    model="google/gemini-2.5-flash",
+    api_key="sk-or-...",
+))
+
+class Summary(BaseModel):
+    title: str
+    bullets: list[str]
+
+result: Summary = await structured_llm_call(
+    prompt="Summarize the attached report.",
+    schema=Summary,
+    feature="reports",      # groups calls in the logs
+    label="exec_summary",   # names this specific call in the logs
+)
+```
+
+The public call surface:
+
+| Function | Use |
+|----------|-----|
+| `structured_llm_call(prompt, schema, feature, label, ...)` | Async, returns a validated Pydantic instance |
+| `structured_llm_call_sync(...)` | Synchronous wrapper around the above |
+| `text_llm_call(prompt, feature, label, ...)` | Async, returns plain text (coerces provider list-content blocks) |
+| `stream_text_with_log(prompt, feature, label, ...)` | Async generator yielding text chunks, logged on completion |
+
+`configure_rate_limit(...)` sets the process-global concurrency cap; `configure_llm_logging(sink)` swaps the log sink (below).
+
+## Logging: agent-readable by default
+
+`LocalYamlLogSink` (the default) writes **two** things to `data/llm-logs/`:
+
+1. **One YAML file per call, laid out verdict-first.** The file opens with a one-line `#` header — `ok`/`ERROR`, feature/label, resolved model, schema, duration, approximate cost — so `head -1 *.yaml` triages a whole run. Small metadata is next; the large `response` and `prompt` blobs are last, so the *head* of the file is the whole story for most reads.
+2. **A compact append-only `index.jsonl`** — one JSON line per call (file, timestamp, feature, label, model, provider, schema, duration, cost, error). Cross-call questions — "which calls errored / were slowest / most expensive / the last call for feature X" — are a single small scan instead of globbing and parsing every YAML.
+
+```
+# ok | reports/exec_summary | google/gemini-2.5-flash | Summary | 1840ms | $0.0007
+# 2026-06-05T14:22:31.004512
+
+timestamp: '2026-06-05T14:22:31.004512'
+feature: reports
+label: exec_summary
+model: google/gemini-2.5-flash
+provider: openrouter
+schema: Summary
+temperature: 0.0
+duration_ms: 1840.2
+approximate_cost: 0.0007
+error: null
+response: ...
+prompt: ...
+```
+
+`approximate_cost` is LiteLLM's per-response estimate for budget visibility — **not** a billing figure (and `None` when the provider does not report it, e.g. streamed calls).
+
+### Write your own `LogSink`
+
+`LogSink` is a one-method `Protocol`. Records (`LLMCallRecord`, a frozen dataclass) are handed to your sink for every call; failures are swallowed so logging can never break a call. To send records somewhere other than local YAML — a database, an HTTP collector, structured stdout — implement `write` and register it:
+
+```python
+import logging
+from pathlib import Path
+from llmkit import LLMCallRecord, configure_llm_logging
+
+logger = logging.getLogger("llm-calls")
+
+class StructuredStdoutSink:
+    def write(self, record: LLMCallRecord) -> Path | None:
+        logger.info(
+            "llm_call",
+            extra={
+                "feature": record.feature,
+                "label": record.label,
+                "model": record.model,
+                "provider": record.provider,
+                "schema": record.schema,
+                "duration_ms": record.duration_ms,
+                "approximate_cost": record.approximate_cost,
+                "error": record.error,
+            },
+        )
+        return None  # nothing persisted to a path
+
+configure_llm_logging(StructuredStdoutSink())   # pass None to disable logging entirely
+```
+
+An OpenTelemetry exporter (e.g. to Langfuse/Phoenix) is a natural future `llmkit[otel]` extra; the pluggable seam makes it a non-breaking addition.
+
+## Configuration
+
+`LLMClientConfig` is flat and carries only what a call needs:
+
+```python
+@dataclass(frozen=True)
+class LLMClientConfig:
+    provider: Provider          # OPENROUTER | OLLAMA | GOOGLE | ANTHROPIC
+    model: str                  # the provider's default model
+    api_key: str | None = None
+    base_url: str | None = None
+```
+
+Per-call `model=` overrides the default, so "strong/small/current" model roles are the host's concern — resolve them to a model string and pass it at the call site. The library has no opinion about roles.
+
+Register the config with `configure_llm_client(source)`, where `source` is a zero-arg callable returning an `LLMClientConfig` (re-read on each provider construction, so it tracks live settings changes).
+
+## Retries
+
+Two retry layers, kept deliberately separate:
+
+- **`with_retries()`** ([`retry.py`](src/llmkit/retry.py)) handles *transient provider* errors (429 / 503 / 5xx; the recoverable set is `LLM_RECOVERABLE_ERRORS`).
+- **instructor's own low `max_retries`** handles *schema-validation* repair (re-ask the model to fix malformed JSON).
+
+## Development
+
+```bash
+uv sync --extra dev
+uv run ruff check . && uv run ruff format --check .
+uv run basedpyright          # 0 errors, 0 warnings — no baseline
+uv run pytest
+```
+
+## Status & support
+
+`llmkit` is a small, opinionated, **best-effort** project, extracted from a real
+application and maintained in the open. It is used in production by its author
+but carries no support SLA. Bug reports and focused pull requests are welcome —
+see [CONTRIBUTING.md](CONTRIBUTING.md). For security issues, see
+[SECURITY.md](SECURITY.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

omg_llmkit-0.1.0/SECURITY.md

@@ -0,0 +1,28 @@
+# Security Policy
+
+## Reporting a vulnerability
+
+Please **do not** open a public issue for security problems.
+
+Report privately through GitHub's
+[private vulnerability reporting](https://github.com/OMGBrews/llmkit/security/advisories/new)
+(the **Security** tab → **Report a vulnerability**). This opens a private
+advisory visible only to the maintainers.
+
+This is a small, best-effort project. There is no formal SLA, but reports are
+taken seriously and acknowledged as soon as practical.
+
+## Scope
+
+`llmkit` is a thin client layer; it holds no credentials of its own and runs no
+network services. The most security-relevant surfaces are:
+
+- **Provider API keys** passed through `LLMClientConfig` — these live in your
+  process, never in `llmkit`.
+- **The default log sink** (`LocalYamlLogSink`) writes prompts and responses to
+  local files under `data/llm-logs/`. Treat that directory as sensitive if your
+  prompts carry secrets, and add it to `.gitignore` (the default for this repo).
+
+## Supported versions
+
+Only the latest released version receives fixes.