Metadata-Version: 2.4
Name: darksyntrix-sdk
Version: 1.3.0
Summary: Official Python SDK for DarkSyntrix — A stealth AI gateway orchestrating 24 private model pipelines through a secure Same-Origin proxy architecture.
Author: VR
License-Expression: MIT
Project-URL: Homepage, https://gitlab.com/llm_model/darksyntrix-sdk
Project-URL: Repository, https://gitlab.com/llm_model/darksyntrix-sdk
Project-URL: Bug Tracker, https://gitlab.com/llm_model/darksyntrix-sdk/-/issues
Project-URL: Documentation, https://gitlab.com/llm_model/darksyntrix-sdk#readme
Keywords: darksyntrix,ai,gateway,sdk,llm,streaming,chat,openai,proxy,machine-learning,artificial-intelligence,api-client,httpx,sse,llama-cpp,qwen,deepseek
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.25.0
Provides-Extra: dev
Requires-Dist: build>=1.0; extra == "dev"
Requires-Dist: twine>=4.0; extra == "dev"
Requires-Dist: wheel>=0.40; extra == "dev"
Dynamic: license-file

# DarkSyntrix Python SDK

[![PyPI Version](https://img.shields.io/pypi/v/darksyntrix-sdk.svg)](https://pypi.org/project/darksyntrix-sdk/)
[![Python Versions](https://img.shields.io/pypi/pyversions/darksyntrix-sdk.svg)](https://pypi.org/project/darksyntrix-sdk/)
[![License](https://img.shields.io/pypi/l/darksyntrix-sdk.svg)](https://github.com/llm_model/darksyntrix-sdk/blob/main/LICENSE)
[![GitLab](https://img.shields.io/badge/GitLab-repo-orange)](https://gitlab.com/llm_model/darksyntrix-sdk)

> Official Python SDK for the **DarkSyntrix** AI Gateway — a stealth Same-Origin proxy architecture orchestrating **24 private model pipelines** (LLM + media) behind a unified OpenAI-compatible API.

---

## Authentication Flow

DarkSyntrix uses a **frontend-first** authentication model. There are two credential types:

### 1. API Key (`vr_live_...`) — for Chat & Media APIs
Users can create their own API keys with configurable rate limits. Admins can create keys with maximum limits. You can get or create your API key from the DarkSyntrix dashboard:

1. Open the **DarkSyntrix dashboard** in your browser
2. **Sign up** or **log in** to your account
3. Navigate to the **API Keys** section
4. Create a new key with your desired rate limits
5. Copy the key and use it in the SDK

```python
from darksyntrix_sdk import DarkSyntrixClient

client = DarkSyntrixClient(
    base_url="https://your-gateway.app",
    api_key="vr_live_..."      # <-- from dashboard
)
```

### 2. Session Token — for Admin Operations
Session tokens are obtained by logging in and are used for key management & telemetry:

```python
client.auth.login("admin_user", "your_password")
# Now client.keys.list(), client.keys.create(), client.telemetry.get() etc. are available
```

**Note:** `client.keys.create()` accepts optional `rate_limit_per_min` and `monthly_request_limit` parameters. When called after login (session), admin gets max limits. When called with an API key, the user gets standard limits.

---

## Quick Start

### Chat (Non-Streaming)

```python
from darksyntrix_sdk import DarkSyntrixClient

client = DarkSyntrixClient(
    base_url="https://your-gateway.app",
    api_key="vr_live_..."
)

response = client.chat.create(
    model="pulse_conversational_1.5b",
    messages=[{"role": "user", "content": "Hello!"}],
    stream=False
)
print(response.choices[0].message.content)
```

### Chat (Streaming)

```python
stream = client.chat.create(
    model="hyperion_r1_reasoning_7b",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True
)
for chunk in stream:
    for choice in chunk.choices:
        print(choice.delta.content, end="", flush=True)
```

### Async Client

```python
import asyncio
from darksyntrix_sdk import AsyncDarkSyntrixClient

async def main():
    async with AsyncDarkSyntrixClient(
        base_url="https://your-gateway.app",
        api_key="vr_live_..."
    ) as client:
        stream = await client.chat.create(
            model="pulse_conversational_1.5b",
            messages=[{"role": "user", "content": "Hello!"}],
            stream=True
        )
        async for chunk in stream:
            for choice in chunk.choices:
                print(choice.delta.content, end="", flush=True)

asyncio.run(main())
```

### Admin: Login & Manage Keys

```python
from darksyntrix_sdk import DarkSyntrixClient

# Works with API key or session token
client = DarkSyntrixClient(
    base_url="https://your-gateway.app",
    api_key="vr_live_..."      # optional — needed for user-level key creation
)

# Login (optional — session grants admin max limits)
client.auth.login("admin_user", "secure_pass123")

# List existing keys
for key in client.keys.list():
    print(f"{key.id}: {key.description} (rate_limit: {key.rate_limit_per_min}/min, monthly: {key.monthly_request_limit})")

# Create a new key with custom rate limits
new_key = client.keys.create(
    "user_name",
    "Production API key",
    rate_limit_per_min=60,
    monthly_request_limit=50000
)
print(f"New key: {new_key}")
```

### Media Processing

```python
client = DarkSyntrixClient(
    base_url="https://your-gateway.app",
    api_key="vr_live_..."
)

# Upload a video
url = client.media.upload("path/to/video.mp4", "video.mp4", "video/mp4")

# Process with RIFE frame interpolation
result = client.media.process(
    model="frame_interpolation_rife",
    cloudinary_url=url,
    parameters={"interpolation_factor": 4}
)
print(result)
```

---

## API Namespaces

| Namespace       | Auth Required | Description                                          |
| --------------- | ------------- | ---------------------------------------------------- |
| `client.auth`   | None          | Register & login to obtain API keys / session tokens |
| `client.keys`   | API Key or Session | List, create, and revoke API keys                |
| `client.chat`   | API Key       | Blocking & streaming chat completions                |
| `client.media`  | API Key       | Upload files & trigger GPU media processing          |
| `client.telemetry` | Session (admin) | Real-time host metrics & database statistics      |

---

## Features

- **Zero bloat** — Only depends on `httpx`. Uses native Python dataclasses.
- **Sync + Async** — Full mirror API with `DarkSyntrixClient` and `AsyncDarkSyntrixClient`.
- **SSE Streaming** — First-class Server-Sent Events parser for real-time token streaming.
- **Connection Pooling** — Built-in `httpx` connection pool with 120s timeout.
- **Full IDE Autocomplete** — Typed dataclass response models.
- **Context Manager Support** — Use `with` / `async with` for automatic cleanup.

---

## Installation

```bash
pip install darksyntrix-sdk
```

Or from source:

```bash
pip install git+https://gitlab.com/llm_model/darksyntrix-sdk.git
```

---

## Supported Models (24 Engines)

### Conversational / General Assistant
- `pulse_conversational_1.5b` • `aurora_core_gemma_1b` • `apex_conversational_llama_3b`
- `infinity_phi_instruct_4` • `sentinel_pulse_qwen_0.5b` • `nebula_core_llama_1b`
- `genesis_smollm_1.7b` • `nexus_quantum_instruct_mini`

### Reasoning / Chain-of-Thought
- `hyperion_r1_reasoning_7b` • `synapse_r1_reasoning_1.5b`

### Code Generation
- `cyber_forge_coder_1.5b` • `matrix_core_coder_3b` • `titan_apex_coder_7b`
- `nova_starcoder_3b` • `vector_gemma_coder_2b` • `synapse_coder_deepseek_1.3b`
- `granite_matrix_coder_3b` • `micro_pulse_coder_0.5b`

### Media Processing (GPU)
- `acoustic_suppression_deepfilter` • `photographic_restoration_gfpgan`
- `avatar_lipsync_hyperlips` • `generative_cinematic_ltx`
- `super_resolution_esrgan` • `frame_interpolation_rife`

---

## License

MIT
