Metadata-Version: 2.4
Name: vitaai
Version: 0.4.0
Summary: Python SDK for VitaAI self-hosted LLM endpoints — drop-in Gemini API replacement
License-Expression: MIT
Project-URL: Homepage, https://github.com/vitainspire/vitaai-python
Project-URL: Documentation, https://github.com/vitainspire/vitaai-python#readme
Keywords: llm,ai,gemini,sdk,vitaai
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Provides-Extra: requests
Requires-Dist: requests>=2.28; extra == "requests"

# vitaai · Python SDK

Drop-in Python SDK for **VitaAI self-hosted LLM endpoints**.  
Designed to mirror the [Google Gemini](https://ai.google.dev/api?lang=python) SDK interface — so migrating existing Gemini projects takes changing one import.

---

## Install

```bash
pip install vitaai
```

---

## Quick start

```python
from vitaai import VitaAI

client = VitaAI(
    api_key="your-api-key",
    base_url="http://your-server-ip:8000"
)

response = client.models.generate_content(
    model="gemma-2b-it",
    contents="What is AI?",
    max_output_tokens=100
)
print(response.text)
print("Tokens:", response.usage_metadata.total_token_count)
```

---

## All endpoints

### 1. Generate content

```python
response = client.models.generate_content(
    model="gemma-2b-it",
    contents="What is machine learning?",
    max_output_tokens=150
)
print(response.text)
print(response.usage_metadata.total_token_count)
```

### 2. Generate with config

```python
response = client.models.generate_content(
    model="gemma-2b-it",
    contents="Explain deep learning",
    config={
        "system_instruction": "You are a teacher. Explain simply.",
        "temperature": 0.7,
        "top_p": 0.9,
        "max_output_tokens": 200
    }
)
print(response.text)
```

### 3. Multi-turn conversation

```python
response = client.models.generate_content(
    model="gemma-2b-it",
    contents=[
        {"role": "user",  "parts": [{"text": "My name is Alex."}]},
        {"role": "model", "parts": [{"text": "Nice to meet you, Alex!"}]},
        {"role": "user",  "parts": [{"text": "What is my name?"}]},
    ]
)
print(response.text)
```

### 4. Streaming

```python
for chunk in client.models.generate_content_stream(
    model="gemma-2b-it",
    contents="Write a short poem about AI",
    max_output_tokens=100
):
    print(chunk.text, end="", flush=True)
print()
```

### 5. Embeddings

```python
response = client.models.embed_content(
    contents="Artificial intelligence is transforming the world"
)
print("Dimensions:", len(response.embedding.values))
print("Values    :", response.embedding.values)
```

### 6. Summarize

```python
response = client.models.summarize(
    contents="Long text you want to summarize...",
    format="bullets",       # "paragraph" or "bullets"
    max_output_tokens=150
)
print(response.summary)
print("Tokens:", response.usage_metadata.total_token_count)
```

### 7. List available models

```python
for model in client.models.list():
    print(model["name"])
    print(model["displayName"])
```

---

## Error handling

```python
from vitaai.transport import AuthenticationError, RateLimitError, ServerError

try:
    response = client.models.generate_content(
        model="gemma-2b-it",
        contents="Hello"
    )
    print(response.text)

except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Too many requests")
except ServerError:
    print("Server error")
except Exception as e:
    print(f"Error: {e}")
```

---

## Client parameters

| Parameter  | Type | Default | Description |
|------------|------|---------|-------------|
| `api_key`  | str  | —       | Your API key. Or set `VITAAI_API_KEY` env var |
| `base_url` | str  | `https://api.vitaai-api.com` | Your server URL |
| `timeout`  | int  | `120`   | Request timeout in seconds. Increase for slow CPU servers |

```python
client = VitaAI(
    api_key="your-key",
    base_url="http://your-server:8000",
    timeout=300
)
```

---

## config options

| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `system_instruction` | str | None | Sets model behaviour |
| `temperature` | float | 0.7 | Randomness (0 = focused, 1 = creative) |
| `top_p` | float | 0.9 | Diversity of responses |
| `max_output_tokens` | int | 100 | Maximum length of response |

---

## Migration from Google Gemini

| Before (google.genai) | After (vitaai) |
|---|---|
| `from google import genai` | `from vitaai import VitaAI` |
| `client = genai.Client()` | `client = VitaAI()` |
| `client.models.generate_content(...)` | `client.models.generate_content(...)` |
| `response.text` | `response.text` ✅ same |
| `response.usage_metadata` | `response.usage_metadata` ✅ same |

---

## Endpoint contract

Your self-hosted backend must expose these routes:

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/v1/models/generate` | Text generation |
| POST | `/v1/models/generate?stream=true` | Streaming |
| POST | `/v1/models/embed` | Embeddings |
| POST | `/v1/models/summarize` | Summarization |
| GET  | `/v1/models/list` | List models |

---

## Environment variables

| Variable | Description |
|---|---|
| `VITAAI_API_KEY` | API key (alternative to passing `api_key=`) |
| `VITAAI_BASE_URL` | Override base URL |
