silvol 0.2.0__tar.gz

silvol-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,66 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]        # → TestPyPI on every push to main
+  release:
+    types: [published]      # → PyPI on tagged GitHub releases
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build wheel + sdist
+        run: python -m build
+
+      - name: Upload dist as artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    environment: testpypi
+    permissions:
+      id-token: write   # OIDC trusted publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.event_name == 'release' && github.event.action == 'published'
+    environment: pypi
+    permissions:
+      id-token: write   # OIDC trusted publishing
+    steps:
+      - name: Download dist artifact
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

silvol-0.2.0/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+.env
+*.egg
+.pytest_cache/
+.mypy_cache/

silvol-0.2.0/CLAUDE.md

@@ -0,0 +1,50 @@
+# CLAUDE.md — silvol-python (PyPI SDK)
+
+> **For Claude:** Full project context lives in the `silvol` repo:
+> `C:\Users\otien\AppData\Local\Temp\silvol\CLAUDE.md` — read that first.
+
+---
+
+## This Repo at a Glance
+
+- **Purpose:** Thin Python SDK wrapping the Silvol OpenAI-compatible API + fine-tuning API
+- **PyPI package name:** `silvol`
+- **Version:** 0.2.0 — added fine-tuning client at `client.finetune` (2026-05-30)
+- **GitHub:** `https://github.com/optimuscodexprimus/silvol-python`
+- **Local clone:** `C:\Users\otien\AppData\Local\Temp\silvol-python`
+- **Default base URL:** `https://api.silvol.ai/v1`
+
+## Package Layout
+
+```
+src/silvol/
+  __init__.py          Exports: Silvol, AsyncSilvol, Finetune, AsyncFinetune, FinetuneError, __version__
+  client.py            Silvol (subclasses openai.OpenAI) + .finetune; AsyncSilvol (subclasses openai.AsyncOpenAI) + .finetune
+  finetune.py          Finetune, AsyncFinetune — wraps /v1/finetune/* endpoints
+  _version.py          __version__ = "0.2.0"
+  integrations/
+    langchain.py       SilvolChat() → ChatOpenAI wired to Silvol gateway
+    crewai.py          SilvolLLM()  → crewai.LLM wired to Silvol gateway
+tests/
+  test_client.py       5 smoke tests (client init + base URL)
+  test_finetune.py     7 smoke tests (attribute attached, dataset encoder, exports)
+.github/workflows/
+  publish.yml          push to main → TestPyPI; tagged release → PyPI (OIDC)
+```
+
+## Building & Testing
+
+```bash
+# Build wheel + sdist
+python -m build
+
+# Run tests (from repo root, with src on PYTHONPATH)
+PYTHONPATH=src python -m pytest tests/ -v
+```
+
+## PyPI Publish Checklist (manual — see Prompt 8 TODOs)
+
+1. Create account at pypi.org + test.pypi.org
+2. `python -m twine upload --repository testpypi dist/*`
+3. `pip install --index-url https://test.pypi.org/simple/ silvol` (verify)
+4. Tag a release → GitHub Actions auto-publishes to production PyPI

silvol-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Silvol
+
+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.

silvol-0.2.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.4
+Name: silvol
+Version: 0.2.0
+Summary: Python SDK for the Silvol inference API — OpenAI-compatible, decentralised GPU.
+Project-URL: Homepage, https://silvol.ai
+Project-URL: Documentation, https://silvol.ai/docs
+Project-URL: Repository, https://github.com/optimuscodexprimus/silvol-python
+Project-URL: Bug Tracker, https://github.com/optimuscodexprimus/silvol-python/issues
+Author-email: Silvol <hello@silvol.ai>
+License: MIT License
+        
+        Copyright (c) 2026 Silvol
+        
+        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.
+License-File: LICENSE
+Keywords: gpu,inference,llm,nosana,openai,silvol
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+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: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25
+Requires-Dist: openai>=1.0
+Provides-Extra: all
+Requires-Dist: crewai>=0.30; extra == 'all'
+Requires-Dist: langchain-openai>=0.1; extra == 'all'
+Provides-Extra: crewai
+Requires-Dist: crewai>=0.30; extra == 'crewai'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: langchain
+Requires-Dist: langchain-openai>=0.1; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# silvol-python
+
+Python SDK for [Silvol](https://silvol.ai) — an OpenAI-compatible inference API running on
+Nosana's decentralised GPU grid.
+
+Drop-in replacement for the OpenAI SDK. Change the base URL and your key; keep the rest
+of your code.
+
+---
+
+## Install
+
+```bash
+pip install silvol
+```
+
+With optional framework integrations:
+
+```bash
+pip install silvol[langchain]   # LangChain
+pip install silvol[crewai]      # CrewAI
+pip install silvol[all]         # both
+```
+
+---
+
+## Quickstart
+
+```python
+from silvol import Silvol
+
+client = Silvol(api_key="sk-svl-...")          # or set SILVOL_API_KEY env var
+
+resp = client.chat.completions.create(
+    model="DeepSeek-R1-Distill-Qwen-7B",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(resp.choices[0].message.content)
+```
+
+Async:
+
+```python
+import asyncio
+from silvol import AsyncSilvol
+
+async def main():
+    client = AsyncSilvol(api_key="sk-svl-...")
+    resp = await client.chat.completions.create(
+        model="DeepSeek-R1-Distill-Qwen-7B",
+        messages=[{"role": "user", "content": "Hello"}],
+        stream=True,
+    )
+    async for chunk in resp:
+        print(chunk.choices[0].delta.content or "", end="", flush=True)
+
+asyncio.run(main())
+```
+
+---
+
+## LangChain
+
+```python
+from silvol.integrations.langchain import SilvolChat
+
+llm = SilvolChat(api_key="sk-svl-...")
+result = llm.invoke("Summarise the Silvol architecture in one sentence.")
+print(result.content)
+```
+
+---
+
+## CrewAI
+
+```python
+from silvol.integrations.crewai import SilvolLLM
+from crewai import Agent, Task, Crew
+
+llm = SilvolLLM(api_key="sk-svl-...")
+
+researcher = Agent(
+    role="Senior Researcher",
+    goal="Uncover groundbreaking technologies in AI",
+    backstory="...",
+    llm=llm,
+)
+```
+
+---
+
+## Models
+
+| Model ID | Context | Notes |
+|---|---|---|
+| `DeepSeek-R1-Distill-Qwen-7B` | 32k | Always-on (free tier) |
+| `llama-3.1-70b` | 128k | On-demand deployment |
+| `qwen-2.5-coder-32b` | 32k | On-demand deployment |
+
+Full list: `GET https://api.silvol.ai/v1/models`
+
+---
+
+## Authentication
+
+Get your API key from the [Silvol Dashboard](https://silvol.ai/dashboard).
+Keys are prefixed `sk-svl-`. Pass it as `api_key=` or set the `OPENAI_API_KEY`
+environment variable (the SDK checks it automatically).
+
+---
+
+## Links
+
+- Docs: [silvol.ai/docs](https://silvol.ai/docs)
+- Dashboard: [silvol.ai/dashboard](https://silvol.ai/dashboard)
+- PyPI: [pypi.org/project/silvol](https://pypi.org/project/silvol)
+- GitHub: [github.com/optimuscodexprimus/silvol-python](https://github.com/optimuscodexprimus/silvol-python)

silvol-0.2.0/README.md

@@ -0,0 +1,117 @@
+# silvol-python
+
+Python SDK for [Silvol](https://silvol.ai) — an OpenAI-compatible inference API running on
+Nosana's decentralised GPU grid.
+
+Drop-in replacement for the OpenAI SDK. Change the base URL and your key; keep the rest
+of your code.
+
+---
+
+## Install
+
+```bash
+pip install silvol
+```
+
+With optional framework integrations:
+
+```bash
+pip install silvol[langchain]   # LangChain
+pip install silvol[crewai]      # CrewAI
+pip install silvol[all]         # both
+```
+
+---
+
+## Quickstart
+
+```python
+from silvol import Silvol
+
+client = Silvol(api_key="sk-svl-...")          # or set SILVOL_API_KEY env var
+
+resp = client.chat.completions.create(
+    model="DeepSeek-R1-Distill-Qwen-7B",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(resp.choices[0].message.content)
+```
+
+Async:
+
+```python
+import asyncio
+from silvol import AsyncSilvol
+
+async def main():
+    client = AsyncSilvol(api_key="sk-svl-...")
+    resp = await client.chat.completions.create(
+        model="DeepSeek-R1-Distill-Qwen-7B",
+        messages=[{"role": "user", "content": "Hello"}],
+        stream=True,
+    )
+    async for chunk in resp:
+        print(chunk.choices[0].delta.content or "", end="", flush=True)
+
+asyncio.run(main())
+```
+
+---
+
+## LangChain
+
+```python
+from silvol.integrations.langchain import SilvolChat
+
+llm = SilvolChat(api_key="sk-svl-...")
+result = llm.invoke("Summarise the Silvol architecture in one sentence.")
+print(result.content)
+```
+
+---
+
+## CrewAI
+
+```python
+from silvol.integrations.crewai import SilvolLLM
+from crewai import Agent, Task, Crew
+
+llm = SilvolLLM(api_key="sk-svl-...")
+
+researcher = Agent(
+    role="Senior Researcher",
+    goal="Uncover groundbreaking technologies in AI",
+    backstory="...",
+    llm=llm,
+)
+```
+
+---
+
+## Models
+
+| Model ID | Context | Notes |
+|---|---|---|
+| `DeepSeek-R1-Distill-Qwen-7B` | 32k | Always-on (free tier) |
+| `llama-3.1-70b` | 128k | On-demand deployment |
+| `qwen-2.5-coder-32b` | 32k | On-demand deployment |
+
+Full list: `GET https://api.silvol.ai/v1/models`
+
+---
+
+## Authentication
+
+Get your API key from the [Silvol Dashboard](https://silvol.ai/dashboard).
+Keys are prefixed `sk-svl-`. Pass it as `api_key=` or set the `OPENAI_API_KEY`
+environment variable (the SDK checks it automatically).
+
+---
+
+## Links
+
+- Docs: [silvol.ai/docs](https://silvol.ai/docs)
+- Dashboard: [silvol.ai/dashboard](https://silvol.ai/dashboard)
+- PyPI: [pypi.org/project/silvol](https://pypi.org/project/silvol)
+- GitHub: [github.com/optimuscodexprimus/silvol-python](https://github.com/optimuscodexprimus/silvol-python)

silvol-0.2.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "silvol"
+dynamic = ["version"]
+description = "Python SDK for the Silvol inference API — OpenAI-compatible, decentralised GPU."
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.10"
+authors = [{ name = "Silvol", email = "hello@silvol.ai" }]
+keywords = ["llm", "inference", "openai", "nosana", "gpu", "silvol"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+  "openai>=1.0",
+  "httpx>=0.25",
+]
+
+[project.optional-dependencies]
+langchain = ["langchain-openai>=0.1"]
+crewai    = ["crewai>=0.30"]
+all       = ["langchain-openai>=0.1", "crewai>=0.30"]
+dev       = ["pytest>=7", "build", "twine"]
+
+[project.urls]
+Homepage      = "https://silvol.ai"
+Documentation = "https://silvol.ai/docs"
+Repository    = "https://github.com/optimuscodexprimus/silvol-python"
+"Bug Tracker" = "https://github.com/optimuscodexprimus/silvol-python/issues"
+
+[tool.hatch.version]
+path = "src/silvol/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/silvol"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

silvol-0.2.0/src/silvol/__init__.py

@@ -0,0 +1,40 @@
+"""
+Silvol — Python SDK for the Silvol inference + fine-tuning API.
+
+Drop-in replacement for the OpenAI SDK pointing at Silvol's
+decentralised GPU gateway, plus a fine-tuning client at ``client.finetune``.
+
+Quickstart::
+
+    from silvol import Silvol
+
+    client = Silvol(api_key="sk-svl-...")
+
+    # Inference
+    resp = client.chat.completions.create(
+        model="DeepSeek-R1-Distill-Qwen-7B",
+        messages=[{"role": "user", "content": "Hello"}],
+    )
+    print(resp.choices[0].message.content)
+
+    # Fine-tuning ($15 flat per run)
+    job = client.finetune.submit_job(
+        job_name="legal-assistant-v1",
+        base_model="llama-3.1-8b",
+        dataset_path="training.jsonl",
+    )
+    client.finetune.upload_dataset(job["dataset_upload_url"], "training.jsonl")
+"""
+
+from ._version import __version__
+from .client import AsyncSilvol, Silvol
+from .finetune import AsyncFinetune, Finetune, FinetuneError
+
+__all__ = [
+    "Silvol",
+    "AsyncSilvol",
+    "Finetune",
+    "AsyncFinetune",
+    "FinetuneError",
+    "__version__",
+]

silvol-0.2.0/src/silvol/_version.py

@@ -0,0 +1 @@
+__version__ = "0.2.0"

silvol-0.2.0/src/silvol/client.py

@@ -0,0 +1,87 @@
+"""
+Silvol Python SDK — sync and async clients.
+
+Drop-in replacements for openai.OpenAI / openai.AsyncOpenAI that point at
+the Silvol inference gateway by default.
+"""
+
+from openai import OpenAI, AsyncOpenAI
+
+from ._version import __version__
+from .finetune import Finetune, AsyncFinetune
+
+__all__ = ["Silvol", "AsyncSilvol"]
+
+_DEFAULT_BASE_URL = "https://api.silvol.ai/v1"
+
+
+class Silvol(OpenAI):
+    """
+    Synchronous Silvol client.
+
+    Usage::
+
+        from silvol import Silvol
+
+        client = Silvol(api_key="sk-svl-...")
+        resp = client.chat.completions.create(
+            model="DeepSeek-R1-Distill-Qwen-7B",
+            messages=[{"role": "user", "content": "Hello"}],
+        )
+        print(resp.choices[0].message.content)
+
+    Fine-tuning is available at ``client.finetune`` — see ``silvol.finetune``.
+    """
+
+    DEFAULT_BASE_URL: str = _DEFAULT_BASE_URL
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url or self.DEFAULT_BASE_URL,
+            **kwargs,
+        )
+        self.finetune: Finetune = Finetune(self)
+
+
+class AsyncSilvol(AsyncOpenAI):
+    """
+    Asynchronous Silvol client.
+
+    Usage::
+
+        import asyncio
+        from silvol import AsyncSilvol
+
+        async def main():
+            client = AsyncSilvol(api_key="sk-svl-...")
+            resp = await client.chat.completions.create(
+                model="DeepSeek-R1-Distill-Qwen-7B",
+                messages=[{"role": "user", "content": "Hello"}],
+            )
+            print(resp.choices[0].message.content)
+
+        asyncio.run(main())
+
+    Fine-tuning is available at ``client.finetune`` — see ``silvol.finetune``.
+    """
+
+    DEFAULT_BASE_URL: str = _DEFAULT_BASE_URL
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url or self.DEFAULT_BASE_URL,
+            **kwargs,
+        )
+        self.finetune: AsyncFinetune = AsyncFinetune(self)

silvol-0.2.0/src/silvol/finetune.py

@@ -0,0 +1,285 @@
+"""
+Silvol fine-tuning API client.
+
+Wraps the gateway endpoints under ``/v1/finetune/*`` with a small typed surface.
+Attached to ``Silvol`` and ``AsyncSilvol`` clients as ``client.finetune``.
+
+Quickstart::
+
+    from silvol import Silvol
+
+    client = Silvol(api_key="sk-svl-...")
+
+    # Submit a training job
+    with open("dataset.jsonl", "rb") as f:
+        job = client.finetune.submit_job(
+            job_name="legal-assistant-v1",
+            base_model="llama-3.1-8b",
+            dataset_file=f,
+        )
+    print(job["id"], job["price_cents"])
+
+    # Poll until ready
+    while True:
+        job = client.finetune.get_job(job["id"])
+        if job["status"] in ("ready", "failed", "cancelled"):
+            break
+
+    # Deploy and use
+    if job["status"] == "ready":
+        client.finetune.deploy_job(job["id"])
+        resp = client.chat.completions.create(
+            model=f"silvol/{job['job_name']}",
+            messages=[{"role": "user", "content": "What is force majeure?"}],
+        )
+"""
+
+from __future__ import annotations
+
+import base64
+from typing import Any, BinaryIO, Iterable, Literal
+
+
+BaseModel = Literal["llama-3.1-8b", "mistral-7b"]
+JobStatus = Literal[
+    "pending", "training", "uploading", "ready",
+    "deploying", "deployed", "failed", "cancelled",
+]
+
+
+def _encode_dataset(dataset: bytes | BinaryIO | str | Iterable[dict]) -> str:
+    """Accept multiple input shapes and return base64-encoded JSONL."""
+    if isinstance(dataset, str):
+        # Already JSONL text
+        data = dataset.encode("utf-8")
+    elif isinstance(dataset, bytes):
+        data = dataset
+    elif hasattr(dataset, "read"):
+        chunk = dataset.read()
+        data = chunk.encode("utf-8") if isinstance(chunk, str) else chunk
+    else:
+        # Iterable of message dicts → JSONL
+        import json
+        data = "\n".join(json.dumps(ex) for ex in dataset).encode("utf-8")
+    return base64.b64encode(data).decode("ascii")
+
+
+def _build_path(*parts: str) -> str:
+    return "/" + "/".join(p.strip("/") for p in parts)
+
+
+# ── Sync ─────────────────────────────────────────────────────────────────────
+
+
+class Finetune:
+    """Synchronous fine-tuning API. Accessed via ``client.finetune``."""
+
+    def __init__(self, client: Any) -> None:
+        # `client` is a Silvol (subclass of OpenAI) — reuse its underlying
+        # httpx client so we share auth, base URL, timeouts, retries, etc.
+        self._client = client
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        # openai SDK exposes `_client._request` on the OpenAI instance; we use
+        # `_client._client.request` via the underlying httpx client for raw access.
+        url = path  # base_url is already set on the openai client
+        # The openai sync client carries a base URL in self.base_url and an
+        # httpx client at self._client. We hit that directly for non-OpenAI routes.
+        http = self._client._client  # httpx.Client
+        full_url = f"{str(self._client.base_url).rstrip('/')}{url}"
+        headers = {
+            "Authorization": f"Bearer {self._client.api_key}",
+            "Content-Type": "application/json",
+        }
+        if "headers" in kwargs:
+            headers.update(kwargs.pop("headers"))
+        resp = http.request(method, full_url, headers=headers, **kwargs)
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("error") or resp.text
+            except Exception:
+                detail = resp.text
+            raise FinetuneError(f"{method} {path} failed ({resp.status_code}): {detail}")
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    # ── Jobs ────────────────────────────────────────────────────────────────
+
+    def submit_job(
+        self,
+        *,
+        job_name: str,
+        base_model: BaseModel,
+        dataset_file: bytes | BinaryIO | str | Iterable[dict] | None = None,
+        dataset_path: str | None = None,
+    ) -> dict[str, Any]:
+        """
+        Submit a training job. Charges $15 via Stripe immediately.
+
+        Provide either ``dataset_file`` (bytes / file object / JSONL string /
+        iterable of message dicts) or ``dataset_path`` (path to a .jsonl file).
+
+        Returns the job record including a ``dataset_upload_url`` — the SDK
+        does NOT upload your dataset for you in this version. Use the returned
+        signed URL with your own HTTP client (or call ``upload_dataset()``).
+        """
+        if dataset_path and not dataset_file:
+            with open(dataset_path, "rb") as f:
+                dataset_file = f.read()
+        if dataset_file is None:
+            raise ValueError("Provide dataset_file or dataset_path")
+
+        return self._request(
+            "POST",
+            "/v1/finetune/jobs",
+            json={
+                "jobName":     job_name,
+                "baseModel":   base_model,
+                "jsonlBase64": _encode_dataset(dataset_file),
+            },
+        )
+
+    def upload_dataset(self, signed_upload_url: str, dataset_path: str) -> None:
+        """
+        Upload a JSONL file to the signed URL returned by ``submit_job``.
+        Training starts automatically on the next poll cycle (~5 min).
+        """
+        with open(dataset_path, "rb") as f:
+            data = f.read()
+        # The signed URL hits Supabase Storage directly, not the gateway —
+        # use a fresh httpx call without our Bearer token.
+        import httpx
+        resp = httpx.put(
+            signed_upload_url,
+            content=data,
+            headers={"Content-Type": "application/jsonl"},
+            timeout=60.0,
+        )
+        if resp.status_code >= 400:
+            raise FinetuneError(f"Dataset upload failed ({resp.status_code}): {resp.text}")
+
+    def list_jobs(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/finetune/jobs")["jobs"]
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        return self._request("GET", _build_path("v1", "finetune", "jobs", job_id))
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """Cancel a pending job. Refund issued automatically."""
+        return self._request("DELETE", _build_path("v1", "finetune", "jobs", job_id))
+
+    def deploy_job(self, job_id: str) -> dict[str, Any]:
+        """Deploy a ready model. Provisions a dedicated GPU node at $0.80/hr."""
+        return self._request(
+            "POST", _build_path("v1", "finetune", "jobs", job_id, "deploy")
+        )
+
+    # ── Models ──────────────────────────────────────────────────────────────
+
+    def list_models(self) -> list[dict[str, Any]]:
+        return self._request("GET", "/v1/finetune/models")["models"]
+
+    def delete_model(self, model_id: str) -> dict[str, Any]:
+        """Stop a deployed model or delete a stored one."""
+        return self._request(
+            "DELETE", _build_path("v1", "finetune", "models", model_id)
+        )
+
+
+# ── Async ────────────────────────────────────────────────────────────────────
+
+
+class AsyncFinetune:
+    """Asynchronous fine-tuning API. Accessed via ``async_client.finetune``."""
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        http = self._client._client  # httpx.AsyncClient
+        full_url = f"{str(self._client.base_url).rstrip('/')}{path}"
+        headers = {
+            "Authorization": f"Bearer {self._client.api_key}",
+            "Content-Type": "application/json",
+        }
+        if "headers" in kwargs:
+            headers.update(kwargs.pop("headers"))
+        resp = await http.request(method, full_url, headers=headers, **kwargs)
+        if resp.status_code >= 400:
+            try:
+                detail = resp.json().get("error") or resp.text
+            except Exception:
+                detail = resp.text
+            raise FinetuneError(f"{method} {path} failed ({resp.status_code}): {detail}")
+        if resp.status_code == 204 or not resp.content:
+            return None
+        return resp.json()
+
+    async def submit_job(
+        self,
+        *,
+        job_name: str,
+        base_model: BaseModel,
+        dataset_file: bytes | BinaryIO | str | Iterable[dict] | None = None,
+        dataset_path: str | None = None,
+    ) -> dict[str, Any]:
+        if dataset_path and not dataset_file:
+            with open(dataset_path, "rb") as f:
+                dataset_file = f.read()
+        if dataset_file is None:
+            raise ValueError("Provide dataset_file or dataset_path")
+
+        return await self._request(
+            "POST",
+            "/v1/finetune/jobs",
+            json={
+                "jobName":     job_name,
+                "baseModel":   base_model,
+                "jsonlBase64": _encode_dataset(dataset_file),
+            },
+        )
+
+    async def upload_dataset(self, signed_upload_url: str, dataset_path: str) -> None:
+        with open(dataset_path, "rb") as f:
+            data = f.read()
+        import httpx
+        async with httpx.AsyncClient(timeout=60.0) as http:
+            resp = await http.put(
+                signed_upload_url,
+                content=data,
+                headers={"Content-Type": "application/jsonl"},
+            )
+            if resp.status_code >= 400:
+                raise FinetuneError(f"Dataset upload failed ({resp.status_code}): {resp.text}")
+
+    async def list_jobs(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/v1/finetune/jobs"))["jobs"]
+
+    async def get_job(self, job_id: str) -> dict[str, Any]:
+        return await self._request("GET", _build_path("v1", "finetune", "jobs", job_id))
+
+    async def cancel_job(self, job_id: str) -> dict[str, Any]:
+        return await self._request("DELETE", _build_path("v1", "finetune", "jobs", job_id))
+
+    async def deploy_job(self, job_id: str) -> dict[str, Any]:
+        return await self._request(
+            "POST", _build_path("v1", "finetune", "jobs", job_id, "deploy")
+        )
+
+    async def list_models(self) -> list[dict[str, Any]]:
+        return (await self._request("GET", "/v1/finetune/models"))["models"]
+
+    async def delete_model(self, model_id: str) -> dict[str, Any]:
+        return await self._request(
+            "DELETE", _build_path("v1", "finetune", "models", model_id)
+        )
+
+
+# ── Errors ───────────────────────────────────────────────────────────────────
+
+
+class FinetuneError(Exception):
+    """Raised on non-2xx responses from the Silvol fine-tuning API."""
+
+    pass

silvol-0.2.0/src/silvol/integrations/__init__.py

@@ -0,0 +1,4 @@
+# Integrations are imported lazily to avoid hard-coding optional dependencies.
+# Import from submodules directly:
+#   from silvol.integrations.langchain import SilvolChat
+#   from silvol.integrations.crewai   import SilvolLLM

silvol-0.2.0/src/silvol/integrations/crewai.py

@@ -0,0 +1,47 @@
+"""
+CrewAI integration for Silvol.
+
+Requires: pip install silvol[crewai]
+"""
+
+from __future__ import annotations
+
+__all__ = ["SilvolLLM"]
+
+_BASE_URL = "https://api.silvol.ai/v1"
+_DEFAULT_MODEL = "DeepSeek-R1-Distill-Qwen-7B"
+
+
+def SilvolLLM(
+    api_key: str | None = None,
+    model: str = _DEFAULT_MODEL,
+    **kwargs,
+):
+    """
+    Return a CrewAI ``LLM`` instance wired to the Silvol gateway.
+
+    Usage::
+
+        from silvol.integrations.crewai import SilvolLLM
+        from crewai import Agent
+
+        llm = SilvolLLM(api_key="sk-svl-...")
+        agent = Agent(role="researcher", goal="...", llm=llm)
+
+    Parameters
+    ----------
+    api_key:
+        Your Silvol API key (``sk-svl-...``).
+    model:
+        Model ID to use.  Defaults to ``DeepSeek-R1-Distill-Qwen-7B``.
+    **kwargs:
+        Forwarded verbatim to ``LLM``.
+    """
+    from crewai import LLM  # noqa: PLC0415
+
+    return LLM(
+        model=f"openai/{model}",
+        api_key=api_key,
+        base_url=_BASE_URL,
+        **kwargs,
+    )

silvol-0.2.0/src/silvol/integrations/langchain.py

@@ -0,0 +1,47 @@
+"""
+LangChain integration for Silvol.
+
+Requires: pip install silvol[langchain]
+"""
+
+from __future__ import annotations
+
+__all__ = ["SilvolChat"]
+
+_BASE_URL = "https://api.silvol.ai/v1"
+_DEFAULT_MODEL = "DeepSeek-R1-Distill-Qwen-7B"
+
+
+def SilvolChat(
+    api_key: str | None = None,
+    model: str = _DEFAULT_MODEL,
+    **kwargs,
+):
+    """
+    Return a LangChain ``ChatOpenAI`` instance wired to the Silvol gateway.
+
+    Usage::
+
+        from silvol.integrations.langchain import SilvolChat
+
+        llm = SilvolChat(api_key="sk-svl-...")
+        print(llm.invoke("Hello"))
+
+    Parameters
+    ----------
+    api_key:
+        Your Silvol API key (``sk-svl-...``).  Falls back to the
+        ``OPENAI_API_KEY`` environment variable if omitted.
+    model:
+        Model ID to use.  Defaults to ``DeepSeek-R1-Distill-Qwen-7B``.
+    **kwargs:
+        Forwarded verbatim to ``ChatOpenAI``.
+    """
+    from langchain_openai import ChatOpenAI  # noqa: PLC0415
+
+    return ChatOpenAI(
+        openai_api_key=api_key,
+        openai_api_base=_BASE_URL,
+        model=model,
+        **kwargs,
+    )

silvol-0.2.0/tests/test_client.py

@@ -0,0 +1,56 @@
+"""
+Smoke tests for the Silvol SDK.
+
+These tests run without a real API key — they verify that the client
+initialises correctly and points at the right base URL.
+"""
+
+from unittest.mock import MagicMock, patch
+
+
+def test_silvol_default_base_url():
+    """Silvol() should use the Silvol gateway base URL by default."""
+    from silvol import Silvol
+
+    with patch("openai.OpenAI.__init__", return_value=None) as mock_init:
+        Silvol(api_key="sk-svl-test")
+        _, kwargs = mock_init.call_args
+        assert kwargs.get("base_url") == "https://api.silvol.ai/v1"
+
+
+def test_silvol_custom_base_url():
+    """Silvol() should respect a caller-supplied base_url."""
+    from silvol import Silvol
+
+    custom = "https://my-proxy.example.com/v1"
+    with patch("openai.OpenAI.__init__", return_value=None) as mock_init:
+        Silvol(api_key="sk-svl-test", base_url=custom)
+        _, kwargs = mock_init.call_args
+        assert kwargs.get("base_url") == custom
+
+
+def test_async_silvol_default_base_url():
+    """AsyncSilvol() should use the Silvol gateway base URL by default."""
+    from silvol import AsyncSilvol
+
+    with patch("openai.AsyncOpenAI.__init__", return_value=None) as mock_init:
+        AsyncSilvol(api_key="sk-svl-test")
+        _, kwargs = mock_init.call_args
+        assert kwargs.get("base_url") == "https://api.silvol.ai/v1"
+
+
+def test_version_exported():
+    """__version__ should be importable from the top-level package."""
+    import silvol
+
+    assert isinstance(silvol.__version__, str)
+    assert silvol.__version__ != ""
+
+
+def test_exports():
+    """Top-level package should export Silvol, AsyncSilvol, __version__."""
+    import silvol
+
+    assert hasattr(silvol, "Silvol")
+    assert hasattr(silvol, "AsyncSilvol")
+    assert hasattr(silvol, "__version__")

silvol-0.2.0/tests/test_finetune.py

@@ -0,0 +1,80 @@
+"""
+Smoke tests for the Silvol fine-tuning SDK.
+
+These tests verify the client attaches the finetune attribute, that the
+dataset encoder accepts multiple input shapes, and that the FinetuneError
+class is exported.
+"""
+
+import base64
+import json
+from unittest.mock import patch
+
+
+def test_finetune_attribute_attached_sync():
+    """Silvol() should expose .finetune as a Finetune instance."""
+    from silvol import Silvol, Finetune
+
+    with patch("openai.OpenAI.__init__", return_value=None):
+        c = Silvol(api_key="sk-svl-test")
+    assert isinstance(c.finetune, Finetune)
+
+
+def test_finetune_attribute_attached_async():
+    """AsyncSilvol() should expose .finetune as an AsyncFinetune instance."""
+    from silvol import AsyncSilvol, AsyncFinetune
+
+    with patch("openai.AsyncOpenAI.__init__", return_value=None):
+        c = AsyncSilvol(api_key="sk-svl-test")
+    assert isinstance(c.finetune, AsyncFinetune)
+
+
+def test_encode_dataset_bytes():
+    """_encode_dataset accepts raw bytes."""
+    from silvol.finetune import _encode_dataset
+
+    raw = b'{"messages":[{"role":"user","content":"hi"}]}\n'
+    encoded = _encode_dataset(raw)
+    assert base64.b64decode(encoded) == raw
+
+
+def test_encode_dataset_string():
+    """_encode_dataset accepts a JSONL string."""
+    from silvol.finetune import _encode_dataset
+
+    raw = '{"messages":[{"role":"user","content":"hi"}]}'
+    encoded = _encode_dataset(raw)
+    assert base64.b64decode(encoded).decode("utf-8") == raw
+
+
+def test_encode_dataset_iterable_of_dicts():
+    """_encode_dataset converts an iterable of dicts to JSONL."""
+    from silvol.finetune import _encode_dataset
+
+    examples = [
+        {"messages": [{"role": "user", "content": "one"}]},
+        {"messages": [{"role": "user", "content": "two"}]},
+    ]
+    encoded = _encode_dataset(examples)
+    decoded = base64.b64decode(encoded).decode("utf-8")
+    lines = decoded.split("\n")
+    assert len(lines) == 2
+    assert json.loads(lines[0])["messages"][0]["content"] == "one"
+    assert json.loads(lines[1])["messages"][0]["content"] == "two"
+
+
+def test_finetune_error_exported():
+    """FinetuneError should be importable from the top-level package."""
+    import silvol
+
+    assert hasattr(silvol, "FinetuneError")
+    assert issubclass(silvol.FinetuneError, Exception)
+
+
+def test_version_bumped_to_0_2():
+    """SDK version should be bumped to 0.2.x for the fine-tuning release."""
+    import silvol
+
+    parts = silvol.__version__.split(".")
+    assert parts[0] == "0"
+    assert int(parts[1]) >= 2, f"expected version >= 0.2.0 for finetune release, got {silvol.__version__}"