Metadata-Version: 2.5
Name: claude-lite-llm
Version: 0.2.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
Provides-Extra: litellm
Requires-Dist: litellm>=1.0.0; extra == 'litellm'
Description-Content-Type: text/markdown

# claude-lite-llm

A lightweight Python wrapper around Anthropic's **Claude Code CLI** and OpenAI's **Codex CLI** that allows developers to run Claude and ChatGPT LLMs programmatically using their active **subscriptions** (`CLAUDE_CODE_TOKEN` and ChatGPT account / `CODEX_ACCESS_TOKEN`) — bypassing pay-per-token API keys.

Also includes built-in custom providers for **LiteLLM** (`ClaudeSubscriptionProvider`, `CodexSubscriptionProvider`, and `register_with_litellm`).

## Features

- **Subscription-Powered**: Authenticate using Claude Code (`CLAUDE_CODE_TOKEN`) and OpenAI Codex CLI subscriptions.
- **Claude & Codex CLI Support**: Unified programmatic access to Anthropic Claude (Sonnet, Opus, Haiku) and OpenAI Codex (o3-mini, o3, gpt-4o).
- **LiteLLM Native Integration**: Exported `ClaudeSubscriptionProvider` and `CodexSubscriptionProvider` classes plus 1-line `register_with_litellm()` for `litellm.completion(model="claude_sub/sonnet")`.
- **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 tool execution and runs sandboxed (`read-only`) 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

# With LiteLLM support:
pip install "claude-lite-llm[litellm]"
```

### Prerequisites

1. **Claude CLI** (if using Claude models):
   ```bash
   npm install -g @anthropic-ai/claude-code
   claude setup-token
   ```
   Add `CLAUDE_CODE_TOKEN` to your app's `.env`:
   ```env
   CLAUDE_CODE_TOKEN=sk-ant-oat01-...
   ```

2. **Codex CLI** (if using Codex / ChatGPT models):
   ```bash
   npm install -g @openai/codex
   codex login
   ```
   Or provide `CODEX_ACCESS_TOKEN` in `.env`.

---

## Usage

### 1. Claude Completion

```python
from claude_lite_llm import completion

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

### 2. Codex Completion (OpenAI / ChatGPT)

```python
from claude_lite_llm import codex_completion

response = codex_completion("Write a Python function to reverse a linked list.", model="o3-mini")
print(response.content)
print(f"Tokens: {response.usage.input_tokens} in / {response.usage.output_tokens} out")
```

### 3. Native Integration with LiteLLM

Use `register_with_litellm()` to route any LiteLLM call through your Claude or Codex subscription:

```python
import litellm
from claude_lite_llm import register_with_litellm

# Register 'claude_sub' and 'codex_sub' custom providers in LiteLLM
register_with_litellm()

# Call Claude via subscription in LiteLLM
claude_res = litellm.completion(
    model="claude_sub/sonnet",
    messages=[{"role": "user", "content": "Explain async/await in Python."}],
)
print(claude_res.choices[0].message.content)

# Call Codex via subscription in LiteLLM
codex_res = litellm.completion(
    model="codex_sub/o3-mini",
    messages=[{"role": "user", "content": "Write a binary search in Python."}],
)
print(codex_res.choices[0].message.content)
```

You can also instantiate the providers directly:
```python
from claude_lite_llm import ClaudeSubscriptionProvider, CodexSubscriptionProvider
import litellm

litellm.custom_provider_map = [
    {"provider": "my_claude", "custom_handler": ClaudeSubscriptionProvider()},
    {"provider": "my_codex", "custom_handler": CodexSubscriptionProvider()},
]
```

### 4. Asynchronous Completions

```python
import asyncio
from claude_lite_llm import acompletion, codex_acompletion


async def main():
    claude_res = await acompletion("Hello from Claude async!")
    print("Claude:", claude_res.content)

    codex_res = await codex_acompletion("Hello from Codex async!", model="o3-mini")
    print("Codex:", codex_res.content)


asyncio.run(main())
```

### 5. Handling Rate Limits & Errors

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

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
