Metadata-Version: 2.5
Name: claude-lite-llm
Version: 0.1.0
Summary: This is an LLM wrapper for claude and its subscription to use via Programming
Project-URL: Homepage, https://github.com/santhoshdasari786/claude-lite-llm
Project-URL: Repository, https://github.com/santhoshdasari786/claude-lite-llm
Project-URL: Issues, https://github.com/santhoshdasari786/claude-lite-llm/issues
Project-URL: Changelog, https://github.com/santhoshdasari786/claude-lite-llm/blob/main/CHANGELOG.md
Author-email: D S Santhosh <santhoshdasari786@gmail.com>
License: MIT
License-File: LICENSE
Keywords: claude,claude-lite-llm
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: python-dotenv>=1.0.0
Description-Content-Type: text/markdown

# claude-lite-llm

A lightweight Python wrapper around Anthropic's `claude` (Claude Code) CLI that allows developers to run Claude LLMs programmatically using their active **Claude Pro/Max subscription** via `CLAUDE_CODE_TOKEN` — bypassing pay-per-token API keys.

## Features

- **Subscription-Powered**: Authenticate using your Claude Code subscription token (`CLAUDE_CODE_TOKEN`) instead of standard Anthropic API keys.
- **LiteLLM / OpenAI Style API**: Simple `completion(...)` and async `acompletion(...)` functions.
- **Flexible Message Formats**: Pass raw prompt strings or conversational message dicts (`[{"role": "user", "content": "..."}]`).
- **Structured Responses**: Access generated text, token usage metrics, latency, and session IDs.
- **Safe Execution**: Disables built-in CLI tool execution (file editing / bash execution) by default for pure text completions.
- **Granular Error Handling**: Dedicated exceptions for rate limits (session quota / 429), authentication failures, and CLI execution errors.

---

## Installation

```bash
pip install claude-lite-llm
```

### Prerequisites

Ensure the Claude Code CLI is installed on your system:
```bash
npm install -g @anthropic-ai/claude-code
# or native install:
# curl -fsSL https://claude.ai/install.sh | bash
```

Generate your subscription token (or retrieve your existing session token):
```bash
claude setup-token
```

Add the token to your `.env` file or export it:
```env
CLAUDE_CODE_TOKEN=sk-ant-oat01-...
```

---

## Usage

### 1. Basic Completion

```python
from claude_lite_llm import completion

response = completion("Explain quantum computing in 2 sentences.")
print(response.content)
print(f"Tokens: {response.usage.input_tokens} in / {response.usage.output_tokens} out")
```

### 2. Multi-Message Conversation

```python
from claude_lite_llm import completion

messages = [
    {"role": "system", "content": "You are an expert Python architect."},
    {"role": "user", "content": "What is the best way to structure an async CLI wrapper?"},
]

response = completion(messages, model="sonnet")
print(response.content)
```

### 3. Using `ClaudeClient`

```python
from claude_lite_llm import ClaudeClient

client = ClaudeClient(
    token="sk-ant-...",  # Optional: loads from CLAUDE_CODE_TOKEN by default
    default_model="sonnet",  # 'sonnet', 'opus', or 'haiku'
)

response = client.completion("Draft a quick haiku about coding.")
print(response.content)
```

### 4. Asynchronous Completion

```python
import asyncio
from claude_lite_llm import acompletion


async def main():
    response = await acompletion("Write a unit test with pytest for a palindrome function.")
    print(response.content)


asyncio.run(main())
```

### 5. Handling Rate Limits & Errors

When session limits or quota thresholds are reached on your Claude subscription, `claude-lite-llm` raises typed exceptions:

```python
from claude_lite_llm import completion
from claude_lite_llm.exceptions import ClaudeRateLimitError, ClaudeAuthError

try:
    response = completion("Hello Claude!")
    print(response.content)
except ClaudeRateLimitError as e:
    # Captures 429 session limits and subscription reset times
    print(f"Rate limit reached: {e}")
except ClaudeAuthError as e:
    print(f"Authentication failure: {e}")
```

---

## Development

```bash
uv sync --all-extras --dev
uv run pytest
uv run ruff check .
uv run mypy
```

Install the git hooks once after cloning:

```bash
uv run pre-commit install
```

## Make targets

| Target          | Description                          |
| --------------- | ------------------------------------ |
| `make install`  | Sync the dev environment             |
| `make lint`     | Ruff lint and format check           |
| `make format`   | Apply Ruff formatting and fixes      |
| `make typecheck`| Run mypy in strict mode              |
| `make test`     | Run the test suite with coverage     |
| `make build`    | Build the sdist and wheel            |
| `make clean`    | Remove build and cache artifacts     |

---

## License

MIT
