smxadk 0.1.0__tar.gz

smxadk-0.1.0/PKG-INFO

@@ -0,0 +1,325 @@
+Metadata-Version: 2.4
+Name: smxadk
+Version: 0.1.0
+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.

smxadk-0.1.0/README.md

@@ -0,0 +1,313 @@
+# 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.

smxadk-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "smxadk"
+version = "0.1.0"
+description = "SyntaxMatrix Agent Development Kit for calling deployed SyntaxMatrix Agent Services."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+  { name = "SyntaxMatrix" }
+]
+dependencies = [
+  "httpx>=0.28.1",
+  "pydantic>=2.10.0",
+  "PyYAML>=6.0.2"
+]
+
+[project.urls]
+Knowledgebase = "https://syntaxmatrix.com/smxadk"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["smxadk*"]
+
+[project.scripts]
+smxadk = "smxadk.cli:main"

smxadk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

smxadk-0.1.0/smxadk/__init__.py

@@ -0,0 +1,9 @@
+from smxadk.client import SMXAgentClient
+from smxadk.schemas import ChatResponse, HealthResponse, TokenUsage
+
+__all__ = [
+    "SMXAgentClient",
+    "ChatResponse",
+    "HealthResponse",
+    "TokenUsage",
+]