kapsl 0.1.0__tar.gz

kapsl-0.1.0/LICENSE

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

kapsl-0.1.0/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: kapsl
+Version: 0.1.0
+Summary: Python SDK for the Kapsl agent runtime
+Author-email: kapsl <kapsl.xyz@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://kapsl.xyz
+Project-URL: Repository, https://github.com/kapsl-xyz/python-sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# kapsl
+
+Python SDK for the [Kapsl](https://kapsl.xyz) agent runtime.
+
+## Install
+
+```bash
+pip install kapsl
+```
+
+## Quick start
+
+```python
+from kapsl import Agent, tool, Client
+
+@tool
+def search(query: str) -> str:
+    """Search the web."""
+    return f"results for {query}"
+
+agent = Agent(
+    name="researcher",
+    model="claude-sonnet-4-20250514",
+    system="You are a research assistant.",
+    tools=[search],
+)
+
+client = Client()
+client.deploy(agent)
+
+run = client.run("researcher", "What is Kapsl?")
+print(run.wait())
+```
+
+## Requirements
+
+- Python 3.10+
+- A running Kapsl daemon (`kapsl start`)

kapsl-0.1.0/README.md

@@ -0,0 +1,38 @@
+# kapsl
+
+Python SDK for the [Kapsl](https://kapsl.xyz) agent runtime.
+
+## Install
+
+```bash
+pip install kapsl
+```
+
+## Quick start
+
+```python
+from kapsl import Agent, tool, Client
+
+@tool
+def search(query: str) -> str:
+    """Search the web."""
+    return f"results for {query}"
+
+agent = Agent(
+    name="researcher",
+    model="claude-sonnet-4-20250514",
+    system="You are a research assistant.",
+    tools=[search],
+)
+
+client = Client()
+client.deploy(agent)
+
+run = client.run("researcher", "What is Kapsl?")
+print(run.wait())
+```
+
+## Requirements
+
+- Python 3.10+
+- A running Kapsl daemon (`kapsl start`)

kapsl-0.1.0/kapsl/__init__.py

@@ -0,0 +1,50 @@
+"""Kapsl Python SDK — define tools, deploy agents, run them."""
+
+from ._tool import tool
+from ._client import Client, Run, KapslError
+
+__all__ = ["tool", "Agent", "Client", "Run", "KapslError"]
+
+
+class Agent:
+    """An agent definition with tools, ready to deploy.
+
+    Example::
+
+        from kapsl import tool, Agent, Client
+
+        @tool
+        def search(query: str) -> str:
+            \"\"\"Search the web.\"\"\"
+            return f"results for {query}"
+
+        agent = Agent(name="researcher", system="You are a researcher.", tools=[search])
+
+        client = Client()
+        client.deploy(agent)
+        run = client.run("researcher", "Find info about Kapsl")
+        print(run.wait())
+    """
+
+    def __init__(
+        self,
+        name: str,
+        *,
+        model: str = "claude-sonnet-4-20250514",
+        system: str | None = None,
+        tools: list | None = None,
+        requirements: list[str] | None = None,
+    ):
+        self.name = name
+        self.model = model
+        self.system = system
+        self.tools = tools or []
+        self.requirements = requirements
+
+        # Validate all tools have the @tool decorator
+        for fn in self.tools:
+            if not getattr(fn, "_kapsl_tool", False):
+                raise ValueError(
+                    f"Function '{fn.__name__}' is not decorated with @tool. "
+                    f"Add @tool before the function definition."
+                )

kapsl-0.1.0/kapsl/_client.py

@@ -0,0 +1,214 @@
+"""Kapsl HTTP client — deploy agents, create runs, stream events."""
+
+import json
+import logging
+from typing import Any, Callable
+
+import requests
+
+from ._tool import _build_tool_defs, generate_tool_code
+
+logger = logging.getLogger("kapsl")
+
+
+class KapslError(Exception):
+    """Error from the Kapsl API."""
+
+    def __init__(self, status_code: int, message: str):
+        self.status_code = status_code
+        self.message = message
+        super().__init__(f"[{status_code}] {message}")
+
+
+def _default_on_event(event: dict) -> None:
+    """Print step progress to stderr.
+
+    Event shape: {"event": "<kind>", "data": {"id": ..., "run_id": ..., "step": N, "kind": "...", "data": {...}}}
+    """
+    kind = event.get("event", "")
+    payload = event.get("data", {})
+    step = payload.get("step", "")
+    inner = payload.get("data", {})
+
+    if kind == "step_started":
+        logger.info("step %s", step)
+    elif kind == "tool_call":
+        logger.info("  tool: %s", inner.get("name", "?"))
+    elif kind == "tool_result":
+        name = inner.get("name", "?")
+        ok = inner.get("ok", False)
+        if ok:
+            logger.info("  result: %s (ok)", name)
+        else:
+            logger.warning("  result: %s (error)", name)
+    elif kind == "run_completed":
+        logger.info("done")
+    elif kind == "run_failed":
+        logger.error("failed: %s", inner.get("error", "unknown error"))
+
+
+class Run:
+    """Handle to a running or completed run."""
+
+    def __init__(self, data: dict, base_url: str):
+        self.id: str = data["id"]
+        self.status: str = data["status"]
+        self.output: Any = data.get("output")
+        self._data = data
+        self._base_url = base_url
+
+    def events(self):
+        """Stream SSE events from the run. Yields dicts with 'event' and 'data' keys."""
+        url = f"{self._base_url}/v1/runs/{self.id}/events"
+        # read timeout only — no connect timeout so initial connection can take time,
+        # but if no data arrives for 60s the stream is considered dead.
+        resp = requests.get(url, stream=True, headers={"Accept": "text/event-stream"}, timeout=(10, 60))
+        resp.raise_for_status()
+
+        event_type = None
+        data_buf = []
+
+        for raw_line in resp.iter_lines(decode_unicode=True):
+            if raw_line is None:
+                continue
+
+            line = raw_line
+
+            if line.startswith("event:"):
+                event_type = line[len("event:"):].strip()
+                continue
+
+            if line.startswith("data:"):
+                data_buf.append(line[len("data:"):].strip())
+                continue
+
+            if line.startswith(":"):
+                # SSE comment / keepalive
+                continue
+
+            if line == "":
+                # Empty line = event boundary
+                if event_type and data_buf:
+                    raw_data = "\n".join(data_buf)
+                    try:
+                        parsed = json.loads(raw_data)
+                    except json.JSONDecodeError:
+                        parsed = raw_data
+
+                    event = {"event": event_type, "data": parsed}
+                    yield event
+
+                    if event_type in ("run_completed", "run_failed", "run_suspended"):
+                        return
+
+                event_type = None
+                data_buf = []
+
+    def refresh(self) -> "Run":
+        """Re-fetch run state from the server."""
+        resp = requests.get(f"{self._base_url}/v1/runs/{self.id}")
+        if resp.status_code != 200:
+            raise KapslError(resp.status_code, resp.text)
+        data = resp.json()
+        self.status = data["status"]
+        self.output = data.get("output")
+        self._data = data
+        return self
+
+    def wait(self, on_event: Callable[[dict], None] | None = _default_on_event) -> Any:
+        """Block until the run reaches a terminal state. Returns the output.
+
+        Args:
+            on_event: Callback for each event. Pass None to suppress output.
+                      Defaults to printing step progress to stderr.
+        """
+        for event in self.events():
+            if on_event:
+                on_event(event)
+        self.refresh()
+        return self.output
+
+
+class Client:
+    """Kapsl API client."""
+
+    def __init__(self, base_url: str = "http://127.0.0.1:50051"):
+        self.base_url = base_url.rstrip("/")
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        url = f"{self.base_url}{path}"
+        resp = requests.request(method, url, **kwargs)
+        if resp.status_code >= 400:
+            try:
+                body = resp.json()
+                msg = body.get("error", resp.text)
+            except Exception:
+                msg = resp.text
+            raise KapslError(resp.status_code, msg)
+        return resp
+
+    def deploy(self, agent) -> dict:
+        """Deploy an agent to the runtime.
+
+        Args:
+            agent: An Agent instance with name, model, system, and tools.
+
+        Returns:
+            The created/updated agent dict from the API.
+        """
+        payload: dict[str, Any] = {
+            "name": agent.name,
+            "model": agent.model,
+        }
+        if agent.system:
+            payload["system"] = agent.system
+        if agent.tools:
+            payload["tools"] = _build_tool_defs(agent.tools)
+            payload["tool_code"] = generate_tool_code(agent.tools)
+        if agent.requirements:
+            payload["requirements"] = agent.requirements
+
+        resp = self._request("POST", "/v1/agents", json=payload)
+        return resp.json()
+
+    def run(self, agent_name: str, input: Any, **overrides) -> Run:
+        """Create a new run for a deployed agent.
+
+        Args:
+            agent_name: Name of the deployed agent.
+            input: The input to send (string or JSON-serializable value).
+            **overrides: Optional per-run overrides (model, system, tools, tool_code).
+
+        Returns:
+            A Run handle for streaming events and getting output.
+        """
+        payload: dict[str, Any] = {"agent": agent_name, "input": input}
+        for key in ("model", "system", "tools", "tool_code"):
+            if key in overrides:
+                payload[key] = overrides[key]
+
+        resp = self._request("POST", "/v1/runs", json=payload)
+        return Run(resp.json(), self.base_url)
+
+    def get_run(self, run_id: str) -> dict:
+        """Fetch a run by ID."""
+        return self._request("GET", f"/v1/runs/{run_id}").json()
+
+    def list_runs(self) -> list[dict]:
+        """List all runs."""
+        return self._request("GET", "/v1/runs").json()
+
+    def list_agents(self) -> list[dict]:
+        """List all registered agents."""
+        return self._request("GET", "/v1/agents").json()
+
+    def dry_run(self, tool_code: str, name: str, input: dict) -> dict:
+        """Execute a single tool call without creating a run.
+
+        Args:
+            tool_code: The complete Python tool script.
+            name: Tool function name to call.
+            input: Input dict for the tool.
+        """
+        payload = {"tool_code": tool_code, "name": name, "input": input}
+        return self._request("POST", "/v1/tools/dry-run", json=payload).json()

kapsl-0.1.0/kapsl/_tool.py

@@ -0,0 +1,277 @@
+"""Tool decorator, JSON Schema generation, and tool code generation."""
+
+import ast
+import inspect
+import re
+import textwrap
+import typing
+from pathlib import Path
+
+
+def tool(fn):
+    """Mark a function as a Kapsl tool.
+
+    Attaches metadata used by Agent and Client to build tool definitions
+    and generate the bundled tool_code script.
+    """
+    hints = typing.get_type_hints(fn)
+    sig = inspect.signature(fn)
+    doc = inspect.getdoc(fn) or ""
+
+    fn._kapsl_tool = True
+    fn._kapsl_name = fn.__name__
+    fn._kapsl_description = doc.split("\n\n")[0].strip()  # first paragraph
+    fn._kapsl_input_schema = _schema_from_hints(sig, hints, doc)
+    return fn
+
+
+# --- Schema generation ---
+
+_TYPE_MAP = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    bool: {"type": "boolean"},
+}
+
+
+def _resolve_type(tp):
+    """Convert a Python type annotation to a JSON Schema fragment."""
+    if tp in _TYPE_MAP:
+        return dict(_TYPE_MAP[tp])
+
+    # Bare list/dict without type args
+    if tp is list:
+        return {"type": "array"}
+    if tp is dict:
+        return {"type": "object"}
+
+    origin = typing.get_origin(tp)
+    args = typing.get_args(tp)
+
+    # list[X]
+    if origin is list:
+        item_type = args[0] if args else str
+        return {"type": "array", "items": _resolve_type(item_type)}
+
+    # dict[str, X]
+    if origin is dict:
+        val_type = args[1] if len(args) > 1 else str
+        return {"type": "object", "additionalProperties": _resolve_type(val_type)}
+
+    import warnings
+    warnings.warn(f"Unsupported type annotation {tp!r}, defaulting to string schema", stacklevel=3)
+    return {"type": "string"}
+
+
+def _is_union(tp):
+    """Check if a type is a Union (typing.Union or PEP 604 X | Y)."""
+    import types as _types
+    return typing.get_origin(tp) is typing.Union or isinstance(tp, _types.UnionType)
+
+
+def _is_optional(tp):
+    """Check if a type is Optional[X] or X | None."""
+    if not _is_union(tp):
+        return False
+    return type(None) in typing.get_args(tp)
+
+
+def _unwrap_optional(tp):
+    """Extract T from Optional[T]."""
+    args = typing.get_args(tp)
+    non_none = [a for a in args if a is not type(None)]
+    return non_none[0] if non_none else str
+
+
+def _parse_arg_descriptions(doc: str) -> dict[str, str]:
+    """Extract parameter descriptions from Google-style docstring Args section."""
+    descriptions = {}
+    in_args = False
+    current_param = None
+    current_desc = []
+
+    for line in doc.split("\n"):
+        stripped = line.strip()
+        if stripped.lower().startswith("args:"):
+            in_args = True
+            continue
+        if in_args:
+            # New section header (e.g., Returns:, Raises:)
+            if stripped and not stripped.startswith(" ") and stripped.endswith(":") and not stripped.startswith("-"):
+                # Check if it's indented relative to Args — if not, it's a new section
+                if not line.startswith(" " * 4) and not line.startswith("\t\t"):
+                    break
+            # Parameter line: "  param_name: description" or "  param_name (type): description"
+            m = re.match(r"\s{2,}(\w+)(?:\s*\([^)]*\))?\s*:\s*(.*)", line)
+            if m:
+                if current_param:
+                    descriptions[current_param] = " ".join(current_desc).strip()
+                current_param = m.group(1)
+                current_desc = [m.group(2)] if m.group(2) else []
+            elif current_param and stripped:
+                # Continuation line
+                current_desc.append(stripped)
+            elif not stripped:
+                if current_param:
+                    descriptions[current_param] = " ".join(current_desc).strip()
+                    current_param = None
+                    current_desc = []
+
+    if current_param:
+        descriptions[current_param] = " ".join(current_desc).strip()
+
+    return descriptions
+
+
+def _schema_from_hints(sig: inspect.Signature, hints: dict, doc: str) -> dict:
+    """Build a JSON Schema object from function signature and type hints."""
+    properties = {}
+    required = []
+    arg_descs = _parse_arg_descriptions(doc)
+
+    for name, param in sig.parameters.items():
+        tp = hints.get(name)
+        if tp is None:
+            tp = str  # no annotation → string
+
+        # Skip return type
+        if name == "return":
+            continue
+
+        optional = _is_optional(tp)
+        if optional:
+            tp = _unwrap_optional(tp)
+
+        prop = _resolve_type(tp)
+        if name in arg_descs:
+            prop["description"] = arg_descs[name]
+
+        properties[name] = prop
+
+        # Required if: no default AND not Optional
+        if param.default is inspect.Parameter.empty and not optional:
+            required.append(name)
+
+    schema = {"type": "object", "properties": properties}
+    if required:
+        schema["required"] = required
+    return schema
+
+
+# --- Tool definitions (for API) ---
+
+def _build_tool_defs(tools: list) -> list[dict]:
+    """Build the tool definitions list for the Anthropic API."""
+    defs = []
+    for fn in tools:
+        defs.append({
+            "name": fn._kapsl_name,
+            "description": fn._kapsl_description,
+            "input_schema": fn._kapsl_input_schema,
+        })
+    return defs
+
+
+# --- Code generation ---
+
+def _extract_imports(fn) -> list[str]:
+    """Extract import statements from the module where fn is defined."""
+    try:
+        source_file = inspect.getfile(fn)
+    except (TypeError, OSError):
+        return []
+
+    try:
+        source = Path(source_file).read_text()
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    try:
+        tree = ast.parse(source)
+    except SyntaxError:
+        return []
+
+    imports = []
+    for node in ast.iter_child_nodes(tree):
+        if isinstance(node, ast.Import):
+            line = ast.get_source_segment(source, node)
+            if line:
+                imports.append(line)
+        elif isinstance(node, ast.ImportFrom):
+            # Skip kapsl imports
+            if node.module and node.module.startswith("kapsl"):
+                continue
+            line = ast.get_source_segment(source, node)
+            if line:
+                imports.append(line)
+
+    return imports
+
+
+def _extract_function_source(fn) -> str:
+    """Get the source of fn, stripping the @tool decorator line."""
+    source = inspect.getsource(fn)
+    source = textwrap.dedent(source)
+    lines = source.split("\n")
+    # Strip @tool decorator line(s)
+    filtered = []
+    skip_next = False
+    for line in lines:
+        stripped = line.strip()
+        if stripped.startswith("@tool"):
+            continue
+        filtered.append(line)
+    return "\n".join(filtered)
+
+
+_DISPATCH_LOOP = '''
+_TOOLS = {%s}
+
+import sys as _sys, json as _json
+for _line in _sys.stdin:
+    _line = _line.strip()
+    if not _line:
+        continue
+    _req = _json.loads(_line)
+    _fn = _TOOLS.get(_req["name"])
+    if _fn is None:
+        print(_json.dumps({"error": f"tool \\'{_req['name']}\\' not found"}))
+    else:
+        try:
+            _result = _fn(**_req["input"])
+            _out = _result if isinstance(_result, (dict, list, str, int, float, bool, type(None))) else str(_result)
+            print(_json.dumps({"output": _out}))
+        except Exception as _e:
+            print(_json.dumps({"error": str(_e)}))
+    _sys.stdout.flush()
+'''
+
+
+def generate_tool_code(tools: list) -> str:
+    """Generate a complete, self-contained Python script for tool execution."""
+    # Collect imports from all tool modules (deduplicated)
+    seen_imports = set()
+    import_lines = []
+    for fn in tools:
+        for imp in _extract_imports(fn):
+            if imp not in seen_imports:
+                seen_imports.add(imp)
+                import_lines.append(imp)
+
+    # Collect function sources
+    func_sources = []
+    for fn in tools:
+        func_sources.append(_extract_function_source(fn))
+
+    # Build tool map string
+    tool_map = ", ".join(f'"{fn._kapsl_name}": {fn._kapsl_name}' for fn in tools)
+
+    parts = []
+    if import_lines:
+        parts.append("\n".join(import_lines))
+        parts.append("")
+    parts.append("\n\n".join(func_sources))
+    parts.append(_DISPATCH_LOOP % tool_map)
+
+    return "\n".join(parts)

kapsl-0.1.0/kapsl.egg-info/PKG-INFO

@@ -0,0 +1,55 @@
+Metadata-Version: 2.4
+Name: kapsl
+Version: 0.1.0
+Summary: Python SDK for the Kapsl agent runtime
+Author-email: kapsl <kapsl.xyz@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://kapsl.xyz
+Project-URL: Repository, https://github.com/kapsl-xyz/python-sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Dynamic: license-file
+
+# kapsl
+
+Python SDK for the [Kapsl](https://kapsl.xyz) agent runtime.
+
+## Install
+
+```bash
+pip install kapsl
+```
+
+## Quick start
+
+```python
+from kapsl import Agent, tool, Client
+
+@tool
+def search(query: str) -> str:
+    """Search the web."""
+    return f"results for {query}"
+
+agent = Agent(
+    name="researcher",
+    model="claude-sonnet-4-20250514",
+    system="You are a research assistant.",
+    tools=[search],
+)
+
+client = Client()
+client.deploy(agent)
+
+run = client.run("researcher", "What is Kapsl?")
+print(run.wait())
+```
+
+## Requirements
+
+- Python 3.10+
+- A running Kapsl daemon (`kapsl start`)

kapsl-0.1.0/kapsl.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+LICENSE
+README.md
+pyproject.toml
+kapsl/__init__.py
+kapsl/_client.py
+kapsl/_tool.py
+kapsl.egg-info/PKG-INFO
+kapsl.egg-info/SOURCES.txt
+kapsl.egg-info/dependency_links.txt
+kapsl.egg-info/requires.txt
+kapsl.egg-info/top_level.txt

kapsl-0.1.0/kapsl.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

kapsl-0.1.0/kapsl.egg-info/requires.txt

@@ -0,0 +1 @@
+requests>=2.28

kapsl-0.1.0/kapsl.egg-info/top_level.txt

@@ -0,0 +1 @@
+kapsl

kapsl-0.1.0/pyproject.toml

@@ -0,0 +1,22 @@
+[project]
+name = "kapsl"
+version = "0.1.0"
+description = "Python SDK for the Kapsl agent runtime"
+requires-python = ">=3.10"
+dependencies = ["requests>=2.28"]
+license = "MIT"
+authors = [{ name = "kapsl", email = "kapsl.xyz@gmail.com" }]
+readme = "README.md"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+]
+
+[project.urls]
+Homepage = "https://kapsl.xyz"
+Repository = "https://github.com/kapsl-xyz/python-sdk"
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"

kapsl-0.1.0/setup.cfg

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