switchlane 0.1.0__tar.gz

switchlane-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+.venv/
+__pycache__/
+.pytest_cache/
+*.egg-info/
+python/build/
+python/dist/
+
+# Local-only files
+local/

switchlane-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Troia Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

switchlane-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: switchlane
+Version: 0.1.0
+Summary: Python SDK for Switchlane runtime agent routing
+Project-URL: Homepage, https://router.troialabs.ai
+Project-URL: Repository, https://github.com/troailabs/switchlane
+Project-URL: Issues, https://github.com/troailabs/switchlane/issues
+Author: Troia Labs
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,mcp,multi-agent,routing
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Requires-Dist: pydantic<3,>=2.6
+Provides-Extra: test
+Requires-Dist: pytest<9,>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# Switchlane Python SDK
+
+A typed sync and async client for the Switchlane runtime routing API.
+
+## Install
+
+```bash
+pip install switchlane
+```
+
+## Use
+
+```python
+from switchlane import Switchlane
+
+with Switchlane("sl_live_...") as client:
+    result = client.route("Review this pull request")
+    if result.meta.abstained:
+        print(result.meta.abstention_reason)
+    else:
+        print(result.recommendations[0].agent_id)
+```
+
+This package is an API client, not an agent framework. The SDK is MIT licensed; the Switchlane server is AGPL-3.0-only.

switchlane-0.1.0/README.md

@@ -0,0 +1,24 @@
+# Switchlane Python SDK
+
+A typed sync and async client for the Switchlane runtime routing API.
+
+## Install
+
+```bash
+pip install switchlane
+```
+
+## Use
+
+```python
+from switchlane import Switchlane
+
+with Switchlane("sl_live_...") as client:
+    result = client.route("Review this pull request")
+    if result.meta.abstained:
+        print(result.meta.abstention_reason)
+    else:
+        print(result.recommendations[0].agent_id)
+```
+
+This package is an API client, not an agent framework. The SDK is MIT licensed; the Switchlane server is AGPL-3.0-only.

switchlane-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "switchlane"
+version = "0.1.0"
+description = "Python SDK for Switchlane runtime agent routing"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Troia Labs" }]
+keywords = ["ai", "agents", "routing", "mcp", "multi-agent"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Typing :: Typed",
+]
+dependencies = [
+  "httpx>=0.27,<1",
+  "pydantic>=2.6,<3",
+]
+
+[project.urls]
+Homepage = "https://router.troialabs.ai"
+Repository = "https://github.com/troailabs/switchlane"
+Issues = "https://github.com/troailabs/switchlane/issues"
+
+[project.optional-dependencies]
+test = ["pytest>=8,<9"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/switchlane"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

switchlane-0.1.0/src/switchlane/__init__.py

@@ -0,0 +1,29 @@
+from .client import AsyncSwitchlane, Switchlane, SwitchlaneError
+from .models import (
+    Agent,
+    AgentListResponse,
+    ExecutionResult,
+    FeedbackResponse,
+    Recommendation,
+    RouteConstraints,
+    RouteMeta,
+    RouteResponse,
+    TaskProfile,
+    UsageResponse,
+)
+
+__all__ = [
+    "Agent",
+    "AgentListResponse",
+    "AsyncSwitchlane",
+    "ExecutionResult",
+    "FeedbackResponse",
+    "Recommendation",
+    "RouteConstraints",
+    "RouteMeta",
+    "RouteResponse",
+    "Switchlane",
+    "SwitchlaneError",
+    "TaskProfile",
+    "UsageResponse",
+]

switchlane-0.1.0/src/switchlane/client.py

@@ -0,0 +1,192 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .models import (
+    AgentListResponse,
+    FeedbackResponse,
+    RouteConstraints,
+    RouteResponse,
+    UsageResponse,
+)
+
+DEFAULT_BASE_URL = "https://router.troialabs.ai"
+
+
+class SwitchlaneError(Exception):
+    def __init__(self, status_code: int, message: str, body: Any = None) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.body = body
+
+
+def _raise_for_status(response: httpx.Response) -> None:
+    if response.is_success:
+        return
+    try:
+        body = response.json()
+    except ValueError:
+        body = {"error": response.text or response.reason_phrase}
+    message = body.get("error", response.reason_phrase) if isinstance(body, dict) else response.reason_phrase
+    raise SwitchlaneError(response.status_code, str(message), body)
+
+
+def _route_payload(
+    task: str,
+    *,
+    input: Mapping[str, Any] | None,
+    constraints: RouteConstraints | Mapping[str, Any] | None,
+    execute: bool,
+    limit: int,
+) -> dict[str, Any]:
+    constraint_data = constraints.model_dump(exclude_none=True) if isinstance(constraints, RouteConstraints) else constraints
+    return {
+        "task": task,
+        "input": dict(input) if input is not None else None,
+        "constraints": dict(constraint_data) if constraint_data is not None else None,
+        "execute": execute,
+        "limit": limit,
+    }
+
+
+class Switchlane:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Switchlane:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+    def route(
+        self,
+        task: str,
+        *,
+        input: Mapping[str, Any] | None = None,
+        constraints: RouteConstraints | Mapping[str, Any] | None = None,
+        execute: bool = False,
+        limit: int = 5,
+    ) -> RouteResponse:
+        response = self._client.post(
+            "/v1/route",
+            json=_route_payload(task, input=input, constraints=constraints, execute=execute, limit=limit),
+        )
+        _raise_for_status(response)
+        return RouteResponse.model_validate(response.json())
+
+    def execute(
+        self,
+        task: str,
+        input: Mapping[str, Any] | None = None,
+        *,
+        constraints: RouteConstraints | Mapping[str, Any] | None = None,
+        limit: int = 5,
+    ) -> RouteResponse:
+        return self.route(task, input=input, constraints=constraints, execute=True, limit=limit)
+
+    def list_agents(self, **params: Any) -> AgentListResponse:
+        response = self._client.get("/v1/agents", params={key: value for key, value in params.items() if value is not None})
+        _raise_for_status(response)
+        return AgentListResponse.model_validate(response.json())
+
+    def feedback(self, agent_id: str, score: float, *, task_id: str | None = None, comment: str | None = None) -> FeedbackResponse:
+        response = self._client.post(
+            "/v1/feedback",
+            json={"agent_id": agent_id, "score": score, "task_id": task_id, "comment": comment},
+        )
+        _raise_for_status(response)
+        return FeedbackResponse.model_validate(response.json())
+
+    def usage(self) -> UsageResponse:
+        response = self._client.get("/v1/billing/usage")
+        _raise_for_status(response)
+        return UsageResponse.model_validate(response.json())
+
+
+class AsyncSwitchlane:
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._client = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            transport=transport,
+            headers={"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"},
+        )
+
+    async def close(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncSwitchlane:
+        return self
+
+    async def __aexit__(self, *_: object) -> None:
+        await self.close()
+
+    async def route(
+        self,
+        task: str,
+        *,
+        input: Mapping[str, Any] | None = None,
+        constraints: RouteConstraints | Mapping[str, Any] | None = None,
+        execute: bool = False,
+        limit: int = 5,
+    ) -> RouteResponse:
+        response = await self._client.post(
+            "/v1/route",
+            json=_route_payload(task, input=input, constraints=constraints, execute=execute, limit=limit),
+        )
+        _raise_for_status(response)
+        return RouteResponse.model_validate(response.json())
+
+    async def execute(
+        self,
+        task: str,
+        input: Mapping[str, Any] | None = None,
+        *,
+        constraints: RouteConstraints | Mapping[str, Any] | None = None,
+        limit: int = 5,
+    ) -> RouteResponse:
+        return await self.route(task, input=input, constraints=constraints, execute=True, limit=limit)
+
+    async def list_agents(self, **params: Any) -> AgentListResponse:
+        response = await self._client.get("/v1/agents", params={key: value for key, value in params.items() if value is not None})
+        _raise_for_status(response)
+        return AgentListResponse.model_validate(response.json())
+
+    async def feedback(self, agent_id: str, score: float, *, task_id: str | None = None, comment: str | None = None) -> FeedbackResponse:
+        response = await self._client.post(
+            "/v1/feedback",
+            json={"agent_id": agent_id, "score": score, "task_id": task_id, "comment": comment},
+        )
+        _raise_for_status(response)
+        return FeedbackResponse.model_validate(response.json())
+
+    async def usage(self) -> UsageResponse:
+        response = await self._client.get("/v1/billing/usage")
+        _raise_for_status(response)
+        return UsageResponse.model_validate(response.json())

switchlane-0.1.0/src/switchlane/models.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class Model(BaseModel):
+    model_config = ConfigDict(extra="allow")
+
+
+class RouteConstraints(Model):
+    max_latency_ms: int | None = Field(default=None, gt=0)
+    max_cost_usd: float | None = Field(default=None, gt=0)
+    min_quality_score: float | None = Field(default=None, ge=0, le=1)
+    quality_weight: float | None = Field(default=None, ge=0, le=1)
+    cost_weight: float | None = Field(default=None, ge=0, le=1)
+    latency_weight: float | None = Field(default=None, ge=0, le=1)
+    min_routing_confidence: float | None = Field(default=None, ge=0, le=1)
+
+
+class Recommendation(Model):
+    agent_id: str
+    provider: str
+    quality_score: float
+    estimated_cost_usd: float | None = None
+    estimated_latency_ms: int | None = None
+    match_reason: str
+    endpoint: str
+
+
+class ExecutionResult(Model):
+    agent_id: str
+    agent_name: str
+    tool_used: str | None = None
+    success: bool
+    content: Any = None
+    error: str | None = None
+    latency_ms: int
+
+
+class TaskProfile(Model):
+    category: str
+    subcategory: str | None = None
+    language: str | None = None
+    input_type: str | None = None
+    output_type: str | None = None
+    complexity: Literal["simple", "medium", "complex"]
+    keywords: list[str] = Field(default_factory=list)
+
+
+class RouteMeta(Model):
+    match_path: str
+    candidates_evaluated: int
+    elapsed_ms: int
+    abstained: bool
+    abstention_reason: Literal[
+        "no_candidates",
+        "constraints_filtered_all_candidates",
+        "top_candidate_below_confidence_threshold",
+    ] | None = None
+    confidence: float | None = None
+
+
+class RouteResponse(Model):
+    recommendations: list[Recommendation]
+    execution: ExecutionResult | None = None
+    task_profile: TaskProfile
+    meta: RouteMeta
+
+
+class Agent(Model):
+    id: str
+    name: str
+    description: str
+    provider: str
+    tags: list[str]
+    combined_score: float
+    pricing_model: str
+    status: str
+
+
+class Pagination(Model):
+    page: int
+    limit: int
+    total: int
+    pages: int
+
+
+class AgentListResponse(Model):
+    agents: list[Agent]
+    pagination: Pagination
+
+
+class FeedbackResponse(Model):
+    accepted: bool
+    agent_id: str
+    new_combined_score: float
+    sample_count: int
+
+
+class UsageResponse(Model):
+    tier: str
+    requests_this_month: int
+    monthly_limit: int
+    estimated_bill_usd: float

switchlane-0.1.0/tests/test_client.py

@@ -0,0 +1,68 @@
+import asyncio
+
+import httpx
+import pytest
+
+from switchlane import AsyncSwitchlane, Switchlane, SwitchlaneError
+
+
+ROUTE_RESPONSE = {
+    "recommendations": [],
+    "task_profile": {
+        "category": "unknown",
+        "subcategory": None,
+        "language": None,
+        "input_type": None,
+        "output_type": None,
+        "complexity": "medium",
+        "keywords": [],
+    },
+    "meta": {
+        "match_path": "llm_intent",
+        "candidates_evaluated": 0,
+        "elapsed_ms": 5,
+        "abstained": True,
+        "abstention_reason": "no_candidates",
+        "confidence": None,
+    },
+}
+
+
+def test_sync_route_parses_abstention_and_sends_auth() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        assert request.headers["Authorization"] == "Bearer sl_live_test"
+        assert request.url.path == "/v1/route"
+        return httpx.Response(200, json=ROUTE_RESPONSE)
+
+    with Switchlane("sl_live_test", base_url="https://example.test", transport=httpx.MockTransport(handler)) as client:
+        result = client.route("unknown task")
+
+    assert result.meta.abstained is True
+    assert result.meta.abstention_reason == "no_candidates"
+
+
+def test_sync_errors_include_status_and_body() -> None:
+    transport = httpx.MockTransport(lambda _: httpx.Response(401, json={"error": "Invalid API key"}))
+    with Switchlane("bad", base_url="https://example.test", transport=transport) as client:
+        with pytest.raises(SwitchlaneError) as caught:
+            client.usage()
+
+    assert caught.value.status_code == 401
+    assert caught.value.body == {"error": "Invalid API key"}
+
+
+def test_async_route() -> None:
+    async def run() -> None:
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.path == "/v1/route"
+            return httpx.Response(200, json=ROUTE_RESPONSE)
+
+        async with AsyncSwitchlane(
+            "sl_live_test",
+            base_url="https://example.test",
+            transport=httpx.MockTransport(handler),
+        ) as client:
+            result = await client.route("unknown task")
+        assert result.meta.confidence is None
+
+    asyncio.run(run())