crtrs-driver 0.1.0__tar.gz

crtrs_driver-0.1.0/LICENSE

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

crtrs_driver-0.1.0/PKG-INFO

@@ -0,0 +1,39 @@
+Metadata-Version: 2.4
+Name: crtrs-driver
+Version: 0.1.0
+Summary: Python client for Driver cloud — run agents, stream events.
+Project-URL: Homepage, https://driver.tors.app
+Project-URL: Issues, https://github.com/CREATORS-INDUSTRIES/driver-python/issues
+Author: CREATORS
+License: MIT
+License-File: LICENSE
+Keywords: agent,ai,cloud,crtrs,driver,sse
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# crtrs-driver
+
+Python client for Driver. Run agents, stream events.
+
+```sh
+pip install crtrs-driver
+```
+
+```python
+from crtrs.driver import Driver
+
+driver = Driver(api_key="dr_...")  # or DRIVER_API_KEY
+
+# Stream events.
+for ev in driver.stream("what is https://ycombinator.com about?"):
+    if ev["kind"] == "action":
+        print(ev["tool"])
+
+# ...or run to completion.
+done = driver.run("what is https://ycombinator.com about?")
+print(done["result"])
+```
+
+Events: `plan`, `plan_item_start`, `action`, `done`, `fatal`.
+
+MIT

crtrs_driver-0.1.0/README.md

@@ -0,0 +1,26 @@
+# crtrs-driver
+
+Python client for Driver. Run agents, stream events.
+
+```sh
+pip install crtrs-driver
+```
+
+```python
+from crtrs.driver import Driver
+
+driver = Driver(api_key="dr_...")  # or DRIVER_API_KEY
+
+# Stream events.
+for ev in driver.stream("what is https://ycombinator.com about?"):
+    if ev["kind"] == "action":
+        print(ev["tool"])
+
+# ...or run to completion.
+done = driver.run("what is https://ycombinator.com about?")
+print(done["result"])
+```
+
+Events: `plan`, `plan_item_start`, `action`, `done`, `fatal`.
+
+MIT

crtrs_driver-0.1.0/examples/run.py

@@ -0,0 +1,57 @@
+"""Manual example: run a real prompt against Driver cloud and print events live.
+
+    export DRIVER_API_KEY=dr_xxxxxxxx
+    python examples/run.py "what is https://ycombinator.com about?"
+
+Optional:
+    export DRIVER_BASE_URL=https://driver.tors.app
+    export DRIVER_DEBUG=1   # dump raw events
+"""
+
+import os
+import sys
+
+from crtrs.driver import Driver, DriverError
+
+
+def main() -> int:
+    if not os.environ.get("DRIVER_API_KEY"):
+        print("set DRIVER_API_KEY (dr_...) — get one from the dashboard", file=sys.stderr)
+        return 2
+
+    prompt = " ".join(sys.argv[1:]) or "what is https://ycombinator.com about?"
+    driver = Driver()  # reads DRIVER_API_KEY / DRIVER_BASE_URL from env
+    debug = bool(os.environ.get("DRIVER_DEBUG"))
+
+    print(f"prompt: {prompt}")
+    done = None
+    try:
+        for ev in driver.stream(prompt):
+            if debug:
+                print("RAW", ev, file=sys.stderr)
+            kind = ev["kind"]
+            if kind == "plan":
+                print("\n[plan]")
+                for i, it in enumerate(ev.get("items") or []):
+                    print(f"  {i + 1}. {it}")
+            elif kind == "plan_item_start":
+                print(f"\n[->] {ev['num'] + 1}. {ev['def']}")
+            elif kind == "action":
+                net = " [net]" if ev.get("is_network") else ""
+                print(f"  . {ev['tool']}{net}")
+            elif kind == "done":
+                done = ev
+    except DriverError as e:
+        print(f"\nfatal: {e}", file=sys.stderr)
+        return 1
+
+    if done is not None:
+        print(f"\n[done] steps={done.get('steps')} errors={done.get('errors')}")
+        print("RESULT:", done.get("result"))
+        for d in done.get("data") or []:
+            print(f"  {d['var']} ({d['label']}): {len(d['value'])} chars")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

crtrs_driver-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "crtrs-driver"
+version = "0.1.0"
+description = "Python client for Driver cloud — run agents, stream events."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [{ name = "CREATORS" }]
+keywords = ["driver", "agent", "ai", "sse", "cloud", "crtrs"]
+dependencies = []
+
+[project.urls]
+Homepage = "https://driver.tors.app"
+Issues = "https://github.com/CREATORS-INDUSTRIES/driver-python/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/crtrs"]

crtrs_driver-0.1.0/src/crtrs/driver/__init__.py

@@ -0,0 +1,154 @@
+"""Python client for Driver cloud — run agents, stream events.
+
+Mirror of the Node client (`@crtrs/driver`): POST a prompt to
+``/api/driver/run`` with a ``dr_`` API key, then stream the agent's events back
+over SSE in real time.
+
+Only five event kinds are surfaced — ``plan``, ``plan_item_start``, ``action``,
+``done``, ``fatal`` — and nothing else (internal kinds, raw tool ids, action
+args and raw error messages are dropped client-side).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+from typing import Callable, Dict, Iterator, List, Optional
+
+__all__ = ["Driver", "DriverError"]
+__version__ = "0.1.0"
+
+DEFAULT_BASE_URL = "https://driver.tors.app"
+RUN_PATH = "/api/driver/run"
+
+# The only event kinds the client surfaces; everything else is dropped.
+ALLOWED_KINDS = frozenset({"plan", "plan_item_start", "action", "done", "fatal"})
+
+Event = Dict[str, object]
+
+
+class DriverError(Exception):
+    """Raised on a failed run or a ``fatal`` event (carries the error category)."""
+
+
+class Driver:
+    """Client for Driver cloud.
+
+    :param api_key: the ``dr_…`` API key (machine credential). Falls back to the
+        ``DRIVER_API_KEY`` environment variable.
+    :param base_url: cloud base URL. Falls back to ``DRIVER_BASE_URL`` then the
+        default (``https://driver.tors.app``).
+    :param timeout: per-read socket timeout in seconds (``None`` = no timeout).
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: Optional[str] = None,
+        timeout: Optional[float] = None,
+    ) -> None:
+        key = api_key or os.environ.get("DRIVER_API_KEY")
+        if not key:
+            raise ValueError(
+                "Driver: missing api_key (pass api_key= or set DRIVER_API_KEY)"
+            )
+        self.api_key = key
+        self.base_url = (base_url or os.environ.get("DRIVER_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        self.timeout = timeout
+
+    def stream(self, prompt: str) -> Iterator[Event]:
+        """Run a prompt and yield each agent event as it arrives.
+
+        Yields the five allowlisted event kinds. Raises :class:`DriverError` on a
+        ``fatal`` event or a non-2xx response.
+        """
+        req = urllib.request.Request(
+            self.base_url + RUN_PATH,
+            data=json.dumps({"prompt": prompt}).encode("utf-8"),
+            method="POST",
+            headers={
+                "Authorization": f"Bearer {self.api_key}",
+                "Content-Type": "application/json",
+                "Accept": "text/event-stream",
+                # Default urllib UA ("Python-urllib/3.x") trips Cloudflare bot
+                # filtering and gets a 403; send our own instead.
+                "User-Agent": f"crtrs-driver/{__version__}",
+            },
+        )
+        try:
+            resp = urllib.request.urlopen(req, timeout=self.timeout)
+        except urllib.error.HTTPError as e:
+            body = _safe_read(e)
+            raise DriverError(
+                f"Driver run failed: HTTP {e.code} {e.reason}" + (f" — {body}" if body else "")
+            ) from None
+
+        with resp:
+            for ev in _parse_sse(resp):
+                # Allowlist: only surface the public kinds so internal events
+                # can never leak to the caller.
+                if ev.get("kind") not in ALLOWED_KINDS:
+                    continue
+                if ev["kind"] == "fatal":
+                    # Only the error category is exposed; raw message stays server-side.
+                    raise DriverError(str(ev.get("semantic") or "fatal"))
+                yield ev
+
+    def run(self, prompt: str, on_event: Optional[Callable[[Event], None]] = None) -> Optional[Event]:
+        """Run a prompt to completion.
+
+        :param on_event: optional callback invoked for every event.
+        :returns: the final ``done`` event, or ``None`` if the stream ended
+            without one.
+        """
+        done: Optional[Event] = None
+        for ev in self.stream(prompt):
+            if on_event is not None:
+                on_event(ev)
+            if ev["kind"] == "done":
+                done = ev
+        return done
+
+
+def _safe_read(e: urllib.error.HTTPError) -> str:
+    try:
+        return e.read().decode("utf-8", "replace")[:500]
+    except Exception:
+        return ""
+
+
+def _parse_sse(resp) -> Iterator[Event]:
+    """Yield parsed JSON events from an SSE stream.
+
+    Handles multi-line ``data:`` fields and blank-line event delimiters.
+    ``data`` blocks that aren't valid JSON are skipped (never surfaced as raw
+    text).
+    """
+    data_lines: List[str] = []
+    for raw in resp:
+        line = raw.decode("utf-8", "replace").rstrip("\r\n")
+        if line == "":  # blank line = end of one SSE event
+            ev = _parse_event(data_lines)
+            data_lines = []
+            if ev is not None:
+                yield ev
+            continue
+        if line.startswith(":"):  # comment / heartbeat
+            continue
+        if line.startswith("data:"):
+            data_lines.append(line[5:].lstrip(" "))
+
+    ev = _parse_event(data_lines)  # flush trailing event with no final blank line
+    if ev is not None:
+        yield ev
+
+
+def _parse_event(data_lines: List[str]) -> Optional[Event]:
+    if not data_lines:
+        return None
+    try:
+        return json.loads("\n".join(data_lines))
+    except json.JSONDecodeError:
+        return None  # non-JSON data is dropped, never surfaced as raw text

crtrs_driver-0.1.0/tests/test_smoke.py

@@ -0,0 +1,80 @@
+"""Smoke test: API surface + SSE parsing against a mock urlopen (no network)."""
+
+import io
+import json
+import os
+import sys
+
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+
+import crtrs.driver as crtrs_driver
+from crtrs.driver import Driver, DriverError
+
+
+class FakeResponse(io.BytesIO):
+    """Byte stream that also works as a context manager (like an HTTP response)."""
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *a):
+        self.close()
+        return False
+
+
+def make_urlopen(captured, body, expect_prompt):
+    def fake_urlopen(req, timeout=None):
+        captured["url"] = req.full_url
+        captured["auth"] = req.headers.get("Authorization")
+        assert json.loads(req.data) == {"prompt": expect_prompt}
+        return FakeResponse(body.encode("utf-8"))
+
+    return fake_urlopen
+
+
+def test_requires_api_key():
+    os.environ.pop("DRIVER_API_KEY", None)
+    try:
+        Driver()
+    except ValueError as e:
+        assert "missing api_key" in str(e)
+    else:
+        raise AssertionError("should require an api_key")
+
+
+def test_stream_allowlist():
+    captured = {}
+    body = (
+        'data: {"kind":"plan","items":["a","b"]}\n\n'
+        'data: {"kind":"step","def":"internal leak"}\n\n'   # hidden kind: dropped
+        "data: not-json should be dropped\n\n"                # non-JSON: dropped
+        'data: {"kind":"action","tool":"http fetching","is_network":true}\n\n'
+        'data: {"kind":"done","result":"ok","steps":2,"errors":0}\n\n'
+    )
+    crtrs_driver.urllib.request.urlopen = make_urlopen(captured, body, "hi")
+
+    driver = Driver(api_key="dr_test")
+    kinds = [ev["kind"] for ev in driver.stream("hi")]
+
+    assert captured["url"].endswith("/api/driver/run")
+    assert captured["auth"] == "Bearer dr_test"
+    assert kinds == ["plan", "action", "done"], kinds
+
+
+def test_fatal_raises():
+    body = 'data: {"kind":"fatal","semantic":"provider"}\n\n'
+    crtrs_driver.urllib.request.urlopen = make_urlopen({}, body, "boom")
+    driver = Driver(api_key="dr_test")
+    try:
+        list(driver.stream("boom"))
+    except DriverError as e:
+        assert str(e) == "provider"
+    else:
+        raise AssertionError("fatal should raise DriverError")
+
+
+if __name__ == "__main__":
+    test_requires_api_key()
+    test_stream_allowlist()
+    test_fatal_raises()
+    print("ok — crtrs-driver smoke test passed")

crtrs_driver-0.1.0/uv.lock

@@ -0,0 +1,8 @@
+version = 1
+revision = 3
+requires-python = ">=3.8"
+
+[[package]]
+name = "crtrs-driver"
+version = "0.1.0"
+source = { editable = "." }