Metadata-Version: 2.4
Name: alaada-orbit
Version: 1.0.0
Summary: Orbit AI Python SDK — official client for the Orbit AI API by Alaada
Author-email: Alaada <alaada@alaada.com>
License: MIT
Project-URL: Homepage, https://alaada.com
Project-URL: Documentation, https://docs.alaada.com
Project-URL: Repository, https://github.com/alaada/orbit-python-sdk
Keywords: orbit,alaada,ai,llm,sdk
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: responses; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"

# alaada — Orbit AI Python SDK

Official Python client for the **Orbit AI API** by [Alaada](https://alaada.com).

```bash
pip install alaada-orbit
```

---

## Quickstart

```python
import alaada as orbit

orbit.configure(api_key="orbit_live_...")

# Single prompt
res = orbit.prompt("simplex1", "What is the capital of France?")
print(res.text)

# Streaming
for chunk in orbit.stream("simplex1", "Write a short poem about the ocean"):
    print(chunk.delta, end="", flush=True)

# Multi-turn chat (history stored automatically)
chat = orbit.chat("simplex1", system="You are a Python coding assistant.")
r1 = chat.send("What is a decorator?")
r2 = chat.send("Show me an example.")   # full context retained
print(r2.text)
```

---

## Models

| Model      | Best for                             |
|------------|--------------------------------------|
| `simplex1` | Fast everyday tasks                  |
| `complex1` | Heavy reasoning, long documents      |
| `imagery1` | Image generation                     |

---

## API reference

### `orbit.configure()`

```python
orbit.configure(
    api_key="orbit_live_...",   # or set ORBIT_API_KEY env var
    privacy=False,              # True = server logs no prompt/response content
    default_model="simplex1",
    timeout=120,
)
```

### `orbit.prompt(model, prompt)`

```python
res = orbit.prompt(
    "simplex1",
    "Summarise this article: ...",
    system      = "You are a helpful assistant.",
    tools       = ["websearch"],        # optional
    temperature = 0.7,
    max_tokens  = 1000,
    privacy     = True,                 # override per-call
    session_id  = "chat_abc123",        # attach to a session
)

print(res.text)        # the response text
print(res.usage)       # {"input_tokens": 12, "output_tokens": 40}
print(res.image_url)   # set when using imagery1
```

### `orbit.stream(model, prompt)`

```python
for chunk in orbit.stream("simplex1", "Tell me a joke"):
    print(chunk.delta, end="", flush=True)
    if chunk.finish_reason == "stop":
        print(f"\n\nTokens used: {chunk.usage}")
```

### `orbit.chat(model)`

```python
session = orbit.chat(
    "complex1",
    system        = "You are an expert data scientist.",
    short_history = True,    # only keep the last chat_max exchanges
    chat_max      = 20,
    privacy       = True,
)

# .send() — full response
res = session.send("Explain gradient descent")
print(res.text)

# .stream() — streamed response
for chunk in session.stream("Now show Python code for it"):
    print(chunk.delta, end="", flush=True)

print(f"\nSession has {session.turns} turns")
session.clear()   # delete session from server
```

### Tools

```python
# Available tools: "websearch", "calculator", "datetime"
res = orbit.prompt(
    "simplex1",
    "What is the latest news on AI regulation?",
    tools=["websearch"],
)
```

---

## Privacy

When `privacy=True`, the Orbit server will **never log** your prompt or response content — only routing metadata (method, status, duration) is recorded.

```python
orbit.configure(api_key="...", privacy=True)   # global
res = orbit.prompt("simplex1", "...", privacy=True)  # per-call
```

---

## Environment variables

| Variable         | Description                                 |
|------------------|---------------------------------------------|
| `ORBIT_API_KEY`  | Your API key (alternative to `configure()`) |
| `ORBIT_BASE_URL` | Override the API server URL                 |

---

## Error handling

```python
from alaada import AuthenticationError, RateLimitError, ValidationError, APIError

try:
    res = orbit.prompt("simplex1", "Hello!")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Resets at {e.reset_at}")
except ValidationError as e:
    print(f"Bad request: {e}")
except APIError as e:
    print(f"Server error: {e}")
```

---

## License
MIT — © Alaada\
All rights reserved by the company and Arzo Das.
