flashlite 0.1.0__tar.gz

flashlite-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

flashlite-0.1.0/.python-version

@@ -0,0 +1 @@
+3.13

flashlite-0.1.0/.vscode/settings.json

@@ -0,0 +1,37 @@
+{
+    "files.exclude": {
+        "**/__pycache__": true,
+        "**/.cache": true,
+        "**/.pytest_cache": true,
+        "**/node_modules": true,
+        "**/.git": true,
+        "**/.DS_Store": true,
+        "**/.ruff_cache": true,
+        "**/.venv": true,
+        "**/*.egg-info": true,
+        "**/.mypy_cache": true,
+    },
+    "search.exclude": {
+        "**/__pycache__": true,
+        "**/.cache": true,
+        "**/.pytest_cache": true,
+        "**/node_modules": true,
+        "**/.git": true,
+        "**/.ruff_cache": true,
+        "**/.venv": true,
+        "**/*.egg-info": true,
+        "**/.mypy_cache": true,
+    },
+    "[python]": {
+        "editor.formatOnSave": true,
+        "editor.defaultFormatter": "charliermarsh.ruff",
+        "editor.codeActionsOnSave": {
+            "source.fixAll.ruff": "always",
+            "source.organizeImports.ruff": "always"
+        }
+    },
+    "ruff.path": [
+        "uvx",
+        "ruff"
+    ]
+}

flashlite-0.1.0/DEV.md

@@ -0,0 +1,209 @@
+# Flashlite Development Guide
+
+## Prerequisites
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) package manager
+
+## Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/flashlite.git
+cd flashlite
+
+# Install dependencies (creates virtualenv automatically)
+uv sync --all-extras
+
+# Activate the virtual environment (optional, uv run handles this)
+source .venv/bin/activate
+```
+
+## Common Commands
+
+### Running Tests
+
+```bash
+# Run all tests
+uv run pytest
+
+# Run with verbose output
+uv run pytest -v
+
+# Run specific test file
+uv run pytest tests/test_client.py
+
+# Run specific test class or function
+uv run pytest tests/test_client.py::TestFlashliteClient::test_complete_with_messages
+
+# Run with coverage
+uv run pytest --cov=flashlite --cov-report=html
+
+# Run tests matching a pattern
+uv run pytest -k "cache"
+```
+
+### Linting & Formatting
+
+```bash
+# Run ruff linter
+uv run ruff check src/
+
+# Auto-fix linting issues
+uv run ruff check src/ --fix
+
+# Format code
+uv run ruff format src/
+
+# Check formatting without changing files
+uv run ruff format src/ --check
+```
+
+### Type Checking
+
+```bash
+# Run mypy
+uv run mypy src/flashlite
+```
+
+### Running All Checks
+
+```bash
+# Run linting, type checking, and tests
+uv run ruff check src/ && uv run mypy src/flashlite && uv run pytest
+```
+
+## Project Structure
+
+```
+flashlite/
+├── src/flashlite/          # Main package
+│   ├── __init__.py         # Public API exports
+│   ├── client.py           # Main Flashlite client
+│   ├── config.py           # Configuration and .env loading
+│   ├── types.py            # Type definitions
+│   ├── core/               # Core completion logic
+│   ├── middleware/         # Request/response middleware
+│   ├── templating/         # Jinja templating
+│   ├── cache/              # Caching backends
+│   ├── observability/      # Logging, metrics, Inspect compat
+│   ├── structured/         # Pydantic structured outputs
+│   ├── conversation/       # Multi-turn conversations, context & multi-agent
+│   │   ├── manager.py      # Single-agent Conversation class
+│   │   ├── context.py      # Context window management
+│   │   └── multi_agent.py  # MultiAgentChat for agent-to-agent conversations
+│   └── tools/              # Tool/function calling helpers
+├── tests/                  # Test suite
+├── examples/               # Example scripts
+│   ├── basic_example.py    # Basic features demo
+│   └── multi_agent_chat.py # Multi-agent conversation example
+├── pyproject.toml          # Project configuration
+├── plan.md                 # Implementation plan
+└── README.md               # User documentation
+```
+
+## Running Examples
+
+```bash
+# Run basic example
+uv run python examples/basic_example.py
+
+# Run multi-agent chat example
+uv run python examples/multi_agent_chat.py
+```
+
+## Testing Without API Keys
+
+Flashlite tests use litellm's `mock_response` feature to avoid hitting real APIs:
+
+```python
+async def test_example():
+    client = Flashlite(default_model="gpt-4o")
+    
+    # mock_response returns a fake response without API calls
+    response = await client.complete(
+        messages="Hello",
+        mock_response="This is a mocked response",
+    )
+    
+    assert response.content == "This is a mocked response"
+```
+
+## Adding New Features
+
+1. **Create a branch** for your feature
+2. **Write tests first** in the appropriate test file
+3. **Implement the feature** in the relevant module
+4. **Run linting and tests** to ensure quality
+5. **Update documentation** if needed
+
+### Middleware Pattern
+
+New features that process requests/responses should use the middleware pattern:
+
+```python
+from flashlite.middleware.base import Middleware
+from flashlite.types import CompletionRequest, CompletionResponse
+
+class MyMiddleware(Middleware):
+    async def __call__(
+        self,
+        request: CompletionRequest,
+        next_handler: Callable[[CompletionRequest], Awaitable[CompletionResponse]],
+    ) -> CompletionResponse:
+        # Pre-processing
+        print(f"Processing request for {request.model}")
+        
+        # Call next middleware/handler
+        response = await next_handler(request)
+        
+        # Post-processing
+        print(f"Got response with {response.usage.total_tokens} tokens")
+        
+        return response
+```
+
+## Environment Variables
+
+Create a `.env` file for local development:
+
+```bash
+# API Keys
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+
+# Flashlite defaults (optional)
+FLASHLITE_DEFAULT_MODEL=gpt-4o
+FLASHLITE_LOG_LEVEL=DEBUG
+```
+
+## Debugging
+
+### Enable Debug Logging
+
+```python
+import logging
+logging.basicConfig(level=logging.DEBUG)
+
+client = Flashlite(log_level="DEBUG", log_requests=True)
+```
+
+### Inspect Middleware Chain
+
+```python
+client = Flashlite(...)
+print(f"Middleware stack: {client._middleware}")
+```
+
+## Release Process
+
+1. Update version in `src/flashlite/__init__.py`
+2. Update `pyproject.toml` version
+3. Run full test suite
+4. Create git tag
+5. Build and publish:
+
+```bash
+uv build
+uv publish
+```

flashlite-0.1.0/LICENSE.md

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

flashlite-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: flashlite
+Version: 0.1.0
+Summary: Batteries-included wrapper for litellm with rate limiting, retries, templating, and more
+Author-email: ndalton12 <niall.dalton12@gmail.com>
+License-File: LICENSE.md
+Requires-Python: >=3.13
+Requires-Dist: jinja2>=3.1.0
+Requires-Dist: litellm>=1.55.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: tenacity>=8.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Flashlite
+
+A batteries-included wrapper for [litellm](https://github.com/BerriAI/litellm) designed for high-volume prompting workloads like evals, agentic loops, and social simulations.
+
+## Features
+
+- **Rate Limiting** - Token bucket algorithm for RPM and TPM limits
+- **Retries** - Exponential backoff with jitter via tenacity
+- **Jinja Templating** - Prompt templates with custom filters
+- **Caching** - In-memory LRU and SQLite disk caching
+- **Structured Outputs** - Native Pydantic model parsing without instructor
+- **Tool/Function Calling** - `@tool` decorator and execution loops
+- **Multi-Turn Conversations** - Conversation management with branching
+- **Cost Tracking** - Token counting and budget limits
+- **Observability** - Structured logging and Inspect framework integration
+- **Async-First** - Native async with sync wrappers
+
+## Installation
+
+```bash
+pip install flashlite
+# or with uv
+uv add flashlite
+```
+
+## Quick Start
+
+```python
+from flashlite import Flashlite
+
+# Create client (loads .env automatically)
+client = Flashlite(default_model="gpt-4o")
+
+# Simple completion
+response = await client.complete(
+    messages="What is the capital of France?"
+)
+print(response.content)
+
+# Sync version
+response = client.complete_sync(messages="Hello!")
+```
+
+### Structured Outputs
+
+```python
+from pydantic import BaseModel, Field
+from flashlite import Flashlite
+
+class Sentiment(BaseModel):
+    label: str = Field(description="positive, negative, or neutral")
+    confidence: float = Field(ge=0, le=1)
+
+client = Flashlite(default_model="gpt-4o")
+
+result: Sentiment = await client.complete(
+    messages="Analyze: 'I love this product!'",
+    response_model=Sentiment,
+)
+print(f"{result.label} ({result.confidence:.0%})")
+```
+
+### Tool/Function Calling
+
+```python
+from flashlite import Flashlite, tool, run_tool_loop
+
+@tool()
+def get_weather(location: str) -> str:
+    """Get weather for a location."""
+    return f"Weather in {location}: 72°F, sunny"
+
+client = Flashlite(default_model="gpt-4o")
+
+result = await run_tool_loop(
+    client=client,
+    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
+    tools=[get_weather],
+)
+print(result.content)
+```
+
+### Parallel Processing
+
+```python
+# Process many requests with concurrency control
+responses = await client.complete_many(
+    requests=[
+        {"messages": f"Summarize: {doc}"}
+        for doc in documents
+    ],
+    max_concurrency=10,
+)
+```
+
+### Caching
+
+```python
+from flashlite import Flashlite, MemoryCache, DiskCache
+
+# In-memory caching
+client = Flashlite(
+    cache=MemoryCache(max_size=1000),
+    default_model="gpt-4o",
+)
+
+# Or persistent disk cache
+client = Flashlite(
+    cache=DiskCache("./cache.db"),
+    default_model="gpt-4o",
+)
+```
+
+### Reasoning Models
+
+```python
+from flashlite import Flashlite, thinking_enabled
+
+client = Flashlite()
+
+# OpenAI o1/o3
+response = await client.complete(
+    model="o3",
+    messages="Solve this complex problem...",
+    reasoning_effort="high",
+)
+
+# Anthropic Claude extended thinking
+response = await client.complete(
+    model="anthropic/claude-sonnet-4-5-20250929",
+    messages="Complex reasoning task...",
+    thinking=thinking_enabled(10000),
+)
+```
+
+## Documentation
+
+- [Quick Start Guide](QUICK_START.md) - Detailed examples for all features
+- [Development Guide](DEV.md) - Setup and contributing
+- [Implementation Plan](plan.md) - Architecture and roadmap
+
+## Requirements
+
+- Python 3.13+
+- litellm
+- pydantic>=2.0
+- jinja2
+- tenacity
+- python-dotenv
+
+## License
+
+MIT