Metadata-Version: 2.4
Name: vitaai
Version: 0.1.0
Summary: Python SDK for VitaAI self-hosted LLM endpoints — drop-in Gemini API replacement
License: 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: License :: OSI Approved :: MIT License
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 exactly — so migrating existing Gemini projects takes changing one import.

```
Base URL: https://api.vitaai-api.com
```

---

## Install

```bash
pip install vitaai            # stdlib only (urllib)
pip install vitaai[requests]  # recommended — better streaming
```

---

## Quick start

```python
from vitaai import VitaAI

client = VitaAI(api_key="your-key")
# or set VITAAI_API_KEY env var and just call VitaAI()

response = client.models.generate_content(
    model="gemma3-27b",
    contents="Explain how AI works in a few words",
)
print(response.text)
```

---

## Usage

### Generate content

```python
response = client.models.generate_content(
    model="gemma3-27b",
    contents="What is the capital of France?",
)
print(response.text)                          # "Paris"
print(response.usage_metadata.total_token_count)
```

### Multi-turn conversation

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

### System instruction

```python
response = client.models.generate_content(
    model="gemma3-27b",
    contents="Tell me a joke.",
    system_instruction="You are a dry, deadpan comedian. Keep it under 2 sentences.",
)
print(response.text)
```

### Generation config

```python
response = client.models.generate_content(
    model="gemma3-27b",
    contents="Write a product description for a smart water bottle.",
    generation_config={
        "temperature": 0.8,
        "max_output_tokens": 256,
        "top_p": 0.95,
    },
)
print(response.text)
```

### Streaming

```python
for chunk in client.models.generate_content_stream(
    model="gemma3-27b",
    contents="Write a short story about a robot who learns to paint.",
):
    print(chunk.text, end="", flush=True)
    if chunk.is_final:
        print()   # newline after stream ends
```

### Embeddings

```python
result = client.models.embed_content(
    model="nomic-embed-text",
    contents="The quick brown fox jumps over the lazy dog",
    task_type="RETRIEVAL_DOCUMENT",
)
vector = result.embedding.values   # List[float]
print(f"Embedding dim: {len(vector)}")
```

### List available models

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

---

## Custom endpoint (GCP deployment)

When you deploy your own model on Google Cloud Run or Vertex AI:

```python
client = VitaAI(
    api_key="your-key",
    base_url="https://your-cloud-run-service-xyz.a.run.app",
)
```

Or set the env var:

```bash
export VITAAI_BASE_URL="https://your-cloud-run-service-xyz.a.run.app"
export VITAAI_API_KEY="your-key"
```

---

## 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     |

---

## Expected 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/list`        | List models        |

See `docs/endpoint-spec.md` for the full request/response schema.

---

## Environment variables

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