Metadata-Version: 2.4
Name: smxadk
Version: 0.1.1
Summary: SyntaxMatrix Agent Development Kit for calling deployed SyntaxMatrix Agent Services.
Author: SyntaxMatrix
Project-URL: Knowledgebase, https://syntaxmatrix.com/smxadk
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.10.0
Requires-Dist: PyYAML>=6.0.2

# smxADK

**smxADK** stands for **SyntaxMatrix Agent Development Kit**.

It is a lightweight Python SDK for calling a deployed SyntaxMatrix Agent Service from any Python project.

---

## Installation

For local development:

```powershell
pip install -e .
```

---

## Basic Usage

```python
from smxadk import SMXAgentClient

client = SMXAgentClient(
    base_url="https://your-agent-service-url"
)

response = client.chat(
    message="Explain RAG in two short sentences.",
    mode="expert",
)

print(response.answer)
print(response.usage.total_tokens)
```

---


---

## Self-Hosting Model

smxADK is designed for **self-hosted SyntaxMatrix deployments**.

The client organisation owns and operates its own backend infrastructure:

```text
Client Application
      ↓
smxADK
      ↓
Client-owned Agent Service
      ↓
Client-owned LiteLLM Proxy
      ↓
Client-owned Ollama / vLLM backends
```

This means:

- the client owns the backend URLs;
- the client pays for their own GPUs, CPUs, storage, and networking;
- the client controls their own data boundary;
- SyntaxMatrix provides the SDK, deployment tooling, templates, and framework.

smxADK should not be hardcoded to use SyntaxMatrix-owned infrastructure.  
The caller must provide the deployed Agent Service URL:

```python
from smxadk import SMXAgentClient

client = SMXAgentClient(
    base_url="https://client-owned-agent-service-url"
)
```

---

## Deployment Configuration

Client organisations define their available model routes in:

```text
smx_deployment.yaml
```

Example:

```yaml
agent_service:
  supported_modes:
    - light
    - medium
    - heavy
    - expert
    - expert-heavy

models:
  light:
    provider: ollama
    model: your-light-model-name
    api_base: https://client-light-ollama-service-url

  medium:
    provider: ollama
    model: your-medium-model-name
    api_base: https://client-medium-ollama-service-url

  heavy:
    provider: ollama
    model: your-heavy-model-name
    api_base: https://client-heavy-ollama-service-url

  expert:
    provider: openai_compatible
    model: your-expert-model-name
    api_base: https://client-expert-vllm-service-url/v1    

  expert-heavy:
    provider: openai_compatible
    model: your-expert-heavy-model-name
    api_base: https://client-expert-heavy-vllm-service-url/v1

```

model: your-light-model-name
model: your-medium-model-name
model: your-expert-model-name

The client does not need to deploy every possible route.  
They only declare the routes they actually have.

---

## Generating Deployment Files

Run:

```powershell
smxadk generate
```

This generates:

```text
../llm-proxy/config.yaml
../agent-service/supported_modes.txt
```

The generated LiteLLM config maps each route to the client-owned backend URL.

The generated `supported_modes.txt` tells the Agent Service which modes it should accept.

---

## Runtime Route Discovery

After deployment, applications can discover available routes:

```python
from smxadk import SMXAgentClient

client = SMXAgentClient(
    base_url="https://client-owned-agent-service-url"
)

print(client.supported_modes())
```

Example output:

```python
["light", "medium", "expert"]
```

If a caller requests a mode that is not supported, the Agent Service rejects it cleanly before calling LiteLLM.

---

## Separation of Responsibilities

```text
smx_deployment.yaml      → client backend routes and model catalogue
LiteLLM Proxy            → backend URL routing
Agent Service            → request validation and orchestration
smxADK                   → client SDK for application developers
```

The ADK only talks to the Agent Service.  
It does not need to know the individual model backend URLs.

---

## Health Check

```python
from smxadk import SMXAgentClient

client = SMXAgentClient(
    base_url="https://your-agent-service-url"
)

health = client.health()

print(health.status)
print(health.supported_modes)
```

---

## Streaming Chat

```python
from smxadk import SMXAgentClient

client = SMXAgentClient(
    base_url="https://your-agent-service-url"
)

for chunk in client.stream_chat(
    message="Explain RAG in two short sentences.",
    mode="expert",
):
    print(chunk, end="", flush=True)
```

---

## Supported Agent Service Endpoints

smxADK currently supports:

```text
GET  /health
POST /chat
POST /chat/stream
```

---

## Explicit Model Routing

The caller must explicitly choose the model route.

Example:

```python
response = client.chat(
    message="Write a short summary.",
    mode="light",
)
```

Available modes depend on the deployed Agent Service.

Current example modes:

```text
light
medium
heavy
expert
expert-heavy
```

---

## Response Shape

`client.chat()` returns a `ChatResponse` object:

```python
response.answer
response.mode
response.usage.prompt_tokens
response.usage.completion_tokens
response.usage.total_tokens
```

---

## Project Structure

```text
smx-adk/
├── pyproject.toml
├── README.md
└── smxadk/
    ├── __init__.py
    ├── client.py
    └── schemas.py
```

---

## Design Goal

smxADK is designed to make deployed SyntaxMatrix Agent Services easy to plug into:

- FastAPI apps
- Dash apps
- Flask apps
- notebooks
- internal tools
- enterprise AI assistants
- SyntaxMatrix-based applications

---

## Licence

Proprietary / SyntaxMatrix.
