llmock 0.1.0__tar.gz

llmock-0.1.0/.github/CODEOWNERS

@@ -0,0 +1 @@
+* @JulienRabault

llmock-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,59 @@
+name: Bug report
+description: Report a runtime, CLI, docs, or provider-shape issue
+title: "[Bug] "
+labels: ["bug"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: Summary
+      description: What is wrong, and what did you expect instead?
+    validations:
+      required: true
+
+  - type: dropdown
+    id: area
+    attributes:
+      label: Area
+      options:
+        - OpenAI-compatible routes
+        - Anthropic routes
+        - Mistral routes
+        - Cohere routes
+        - Gemini routes
+        - Groq routes
+        - Together routes
+        - Perplexity routes
+        - AI21 routes
+        - xAI routes
+        - Batch endpoints
+        - Chaos / config / CLI
+        - Packaging / release / CI
+        - Docs / examples
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Reproduction
+      description: Include request payloads, config, and commands when possible.
+      placeholder: |
+        1. Start LLMock with ...
+        2. Send request to ...
+        3. Observe ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behavior
+    validations:
+      required: true
+
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Python version, install method, OS, and LLMock version if relevant.

llmock-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: true

llmock-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,39 @@
+name: Feature request
+description: Propose a scoped improvement to LLMock
+title: "[Feature] "
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What real user or testing problem does this solve?
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed solution
+      description: Keep it concrete and scoped.
+    validations:
+      required: true
+
+  - type: textarea
+    id: tradeoffs
+    attributes:
+      label: Tradeoffs
+      description: Maintenance cost, compatibility impact, or scope concerns.
+
+  - type: dropdown
+    id: fit
+    attributes:
+      label: Why it fits LLMock
+      options:
+        - Improves resilience testing
+        - Improves API fidelity
+        - Improves onboarding or adoption
+        - Improves packaging or maintainability
+        - Not sure
+    validations:
+      required: true

llmock-0.1.0/.github/dependabot.yml

@@ -0,0 +1,13 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5
+
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+    open-pull-requests-limit: 5

llmock-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,16 @@
+## Summary
+
+- what changed
+- why it changed
+- any provider or endpoint impact
+
+## Validation
+
+- [ ] `python -m ruff check llmock tests examples/retry_with_openai.py`
+- [ ] `pytest -q`
+- [ ] docs updated if install, config, or API behavior changed
+
+## Risks
+
+- behavior or compatibility risks
+- release or migration impact

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

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run Ruff
+        run: python -m ruff check llmock tests
+
+  tests:
+    name: Tests
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest
+
+  package:
+    name: Build package
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install build tooling
+        run: python -m pip install -e ".[dev]"
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*

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

@@ -0,0 +1,87 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build and verify release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.11"
+          cache: pip
+
+      - name: Install release tooling
+        run: python -m pip install -e ".[dev]"
+
+      - name: Lint
+        run: python -m ruff check llmock tests examples/retry_with_openai.py
+
+      - name: Test
+        run: pytest -q
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Check package metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distributions
+        uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/*
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/llmock/
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist
+
+      - name: Create GitHub release
+        uses: softprops/action-gh-release@v2
+        with:
+          generate_release_notes: true
+          files: dist/*

llmock-0.1.0/.gitignore

@@ -0,0 +1,45 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+MANIFEST
+
+# Testing
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Environment variables
+.env
+.env.*
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Internal agent files
+agents/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log

llmock-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,216 @@
+# LLMock Architecture
+
+## Overview
+
+LLMock is a zero-cost local mock server that presents OpenAI-compatible (and provider-native) HTTP APIs. Developers point their LLM SDK at `http://localhost:8000` instead of a real provider endpoint, then use environment variables or runtime settings to inject latency, rate-limit errors (429), and server errors (500 / 503). This lets integration tests exercise retry logic, backoff strategies, and error-handling paths without spending tokens or requiring network access.
+
+---
+
+## Request Flow
+
+```
+Client (SDK / curl)
+        │
+        ▼
+┌───────────────────────────────────────────────┐
+│              FastAPI Application              │
+│                                               │
+│   ┌───────────────────────────────────────┐   │
+│   │          ChaosMiddleware              │   │
+│   │  (latency injection + error sampling) │   │
+│   └─────────────────┬─────────────────────┘   │
+│                     │                         │
+│   ┌─────────────────▼─────────────────────┐   │
+│   │            API Router                 │   │
+│   │  (provider-specific prefix & schema)  │   │
+│   └─────────────────┬─────────────────────┘   │
+│                     │                         │
+│   ┌─────────────────▼─────────────────────┐   │
+│   │          Mock Response                │   │
+│   │  (deterministic, schema-correct JSON) │   │
+│   └───────────────────────────────────────┘   │
+└───────────────────────────────────────────────┘
+        │
+        ▼
+Client receives response (or injected error)
+```
+
+The `/health` endpoint bypasses the middleware entirely so monitoring systems remain reliable during chaos tests.
+
+---
+
+## Chaos Middleware
+
+**File:** `llmock/chaos.py`
+
+### `ChaosSettings` dataclass
+
+```python
+@dataclass
+class ChaosSettings:
+    latency_ms: int = 0
+    error_rate_429: float = 0.0
+    error_rate_500: float = 0.0
+    error_rate_503: float = 0.0
+```
+
+Loaded from environment variables at startup via `ChaosSettings.from_env()`:
+
+| Variable              | Default | Effect                                      |
+|-----------------------|---------|---------------------------------------------|
+| `LLMOCK_LATENCY_MS`   | `0`     | Fixed delay added before every response     |
+| `LLMOCK_ERROR_RATE_429` | `0.0` | Probability (0–1) of returning a 429        |
+| `LLMOCK_ERROR_RATE_500` | `0.0` | Probability (0–1) of returning a 500        |
+| `LLMOCK_ERROR_RATE_503` | `0.0` | Probability (0–1) of returning a 503        |
+
+Each app instance receives a `ChaosSettings` object through `create_app(chaos=...)`. The module-level `chaos_settings` value is only used to build the default exported `app`.
+
+### Sampling Logic
+
+On each request the middleware:
+
+1. Sleeps for `latency_ms / 1000` seconds (if > 0).
+2. Draws a single random float `r ∈ [0, 1)`.
+3. Walks error rates in priority order `429 → 503 → 500`, accumulating a cumulative probability. If `r < cumulative`, returns that error immediately.
+
+This cumulative approach means rates are additive and predictable: setting all three to `0.33` gives roughly equal chance of each error and ~1% pass-through.
+
+---
+
+## Router Pattern
+
+**Directory:** `llmock/routers/`
+
+Each provider has its own Python module with a consistent structure:
+
+```
+llmock/routers/
+├── openai.py       # /v1/...  (OpenAI-compatible)
+├── anthropic.py    # /anthropic/v1/...
+├── mistral.py      # /v1/...  (Mistral-compatible)
+├── gemini.py       # /v1beta/models/...
+├── cohere.py       # /v2/...
+├── groq.py         # /openai/v1/...
+├── together.py     # /together/v1/...
+├── perplexity.py   # /pplx/v1/...
+├── ai21.py         # /ai21/v1/...
+├── xai.py          # /xai/v1/...
+└── batch.py        # /v1/files, /v1/batches (Batch API)
+```
+
+### Module structure (example: `openai.py`)
+
+```python
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter(prefix="/v1", tags=["openai"])
+
+# 1. Request models (Pydantic)
+class ChatCompletionRequest(BaseModel): ...
+
+# 2. Response models (Pydantic)
+class ChatCompletionResponse(BaseModel): ...
+
+# 3. Endpoint handlers
+@router.post("/chat/completions", response_model=ChatCompletionResponse)
+def chat_completions(request: ChatCompletionRequest) -> ChatCompletionResponse:
+    # Build and return a deterministic mock response
+    ...
+```
+
+Routers are registered in `llmock/main.py` via `app.include_router(...)`.
+
+---
+
+## Batch API Simulation
+
+**File:** `llmock/routers/batch.py`
+
+Simulates the full OpenAI Batch API async JSONL workflow:
+
+| Step | Request | Description |
+|------|---------|-------------|
+| 1 | `POST /v1/files` | Upload a JSONL request file |
+| 2 | `POST /v1/batches` | Create a batch job referencing the file |
+| 3 | `GET /v1/batches/{id}` | Poll status (`validating → in_progress → completed`) |
+| 4 | `GET /v1/files/{id}/content` | Download the JSONL results file |
+| 5 | `POST /v1/batches/{id}/cancel` | Cancel an in-progress batch |
+
+All state is held in in-memory dictionaries (`_files`, `_batches`). Batches complete automatically after a configurable delay (`_BATCH_DELAY`, default 3 s) via a FastAPI `BackgroundTasks` coroutine.
+
+---
+
+## Adding a New Provider
+
+1. **Create the router file** at `llmock/routers/myprovider.py`:
+
+```python
+from fastapi import APIRouter
+from pydantic import BaseModel
+
+router = APIRouter(prefix="/myprovider/v1", tags=["myprovider"])
+
+class MyRequest(BaseModel):
+    model: str
+    prompt: str
+
+@router.post("/generate")
+def generate(request: MyRequest) -> dict:
+    return {
+        "id": "mock-id",
+        "model": request.model,
+        "output": f"Mock response from {request.model}.",
+    }
+```
+
+2. **Register the router** in `llmock/main.py`:
+
+```python
+from llmock.routers import myprovider as myprovider_router
+# ...
+app.include_router(myprovider_router.router)
+```
+
+3. **Add tests** in `tests/test_myprovider.py`:
+
+```python
+from fastapi.testclient import TestClient
+from llmock.main import create_app
+
+client = TestClient(create_app())
+
+def test_generate():
+    r = client.post("/myprovider/v1/generate", json={"model": "my-model-1", "prompt": "Hello"})
+    assert r.status_code == 200
+    assert r.json()["model"] == "my-model-1"
+```
+
+---
+
+## Test Architecture
+
+**Directory:** `tests/`
+
+```
+tests/
+├── test_openai.py       # OpenAI chat completions, embeddings, models
+├── test_anthropic.py    # Anthropic Messages API
+├── test_mistral.py      # Mistral chat completions
+├── test_providers.py    # Gemini, Cohere, Groq, Together, Perplexity, AI21, xAI
+├── test_batch.py        # Full Batch API workflow (upload → create → poll → results)
+└── test_chaos.py        # ChaosMiddleware latency and error injection
+```
+
+### Key patterns
+
+- **`TestClient`** (synchronous): All tests use `fastapi.testclient.TestClient` wrapping `create_app()`. This avoids the async overhead of `httpx.AsyncClient` while remaining ASGI-compatible.
+- **`create_app(chaos=...)`**: The app factory accepts an optional `ChaosSettings` argument, allowing tests to inject specific chaos configurations without touching global state or environment variables.
+- **Direct state injection**: Batch API tests that need a specific pre-condition (e.g., `in_progress` status) write directly into the router's `_batches` dict rather than racing against background tasks.
+
+### Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest
+```

llmock-0.1.0/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project should be documented in this file.
+
+## [0.1.0] - 2026-03-20
+
+- initial public release of LLMock
+- multi-provider mock API support across OpenAI, Anthropic, Mistral, Cohere, Gemini, Groq, Together AI, Perplexity, AI21, and xAI
+- configurable chaos injection with latency and per-status error probabilities
+- configurable success payload styles
+- provider-specific batch endpoint simulation
+- PyPI-oriented CLI packaging and release workflows

llmock-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,27 @@
+# Code of Conduct
+
+This project expects respectful, direct, and constructive collaboration.
+
+## Expected behavior
+
+- discuss technical points in good faith
+- focus on concrete behavior, tradeoffs, and evidence
+- be respectful in disagreement
+- assume contributors are trying to improve the project
+- keep review feedback specific and actionable
+
+## Unacceptable behavior
+
+- harassment, intimidation, or personal attacks
+- discriminatory or hateful language
+- repeated bad-faith argumentation
+- doxxing or sharing private information without consent
+- derailing collaboration with hostility or abuse
+
+## Scope
+
+This applies to issues, pull requests, discussions, and any other project spaces.
+
+## Enforcement
+
+Maintainers may edit, remove, or reject contributions and interactions that harm the project environment.

llmock-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing to LLMock
+
+Thanks for contributing.
+
+LLMock is intentionally narrow in scope: it is a local mock server for testing LLM client resilience, retries, fallbacks, and integration behavior. Contributions are most useful when they improve fidelity, reliability, or adoption without turning the project into a full provider emulator.
+
+## Good contribution targets
+
+- fix mismatches between runtime behavior and provider docs
+- add tests for provider-specific request and error shapes
+- improve batch endpoint coverage
+- improve docs, examples, and onboarding
+- add deterministic testing capabilities
+- tighten packaging, release automation, and CI
+
+## Changes that need extra care
+
+- large new provider surfaces
+- features that increase maintenance cost a lot
+- behavior that diverges from official provider APIs without being documented
+- breaking CLI, config, or response-shape changes
+
+If a change is large or changes public behavior, open an issue first.
+
+## Local setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run checks before opening a pull request:
+
+```bash
+python -m ruff check llmock tests examples/retry_with_openai.py
+pytest -q
+python -m build
+```
+
+## Pull request expectations
+
+- keep changes scoped and explain the user-facing impact clearly
+- add or update tests for behavioral changes
+- update [README.md](/C:/Users/julie/Documents/Code_space/LLMock/README.md) when install, config, or API behavior changes
+- preserve provider-specific response and error shapes where possible
+- avoid unrelated refactors in the same pull request
+
+## Design principles
+
+- local-first and cheap to run
+- explicit over magical
+- useful for resilience testing before it is exhaustive
+- predictable defaults, configurable failure modes

llmock-0.1.0/LICENSE

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