Metadata-Version: 2.4
Name: darksyntrix-sdk
Version: 1.1.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
API keys are **admin-created** and distributed to users. You get 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. Request a key — an admin will provision one for you
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.telemetry.get() etc. are available
```

**Note:** API key creation (`client.keys.create()`) is **admin-only**. Regular users get their keys from the dashboard.

---

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

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

# Login (requires existing admin account)
client.auth.login("admin_user", "secure_pass123")

# List existing keys
for key in client.keys.list():
    print(f"{key.id}: {key.description} (active: {key.is_active})")

# Create a new key for a user (admin only)
new_key = client.keys.create("user_name", "Production API key")
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`   | Session (admin) | 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
