selfship-ai 0.1.0__tar.gz

selfship_ai-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+bin/
+__pycache__/
+*.py[cod]
+tmp/*
+!tmp/.gitkeep
+.env
+.env.local
+webapp/.env.local
+webapp/node_modules/
+pr-runner/node_modules/
+pr-runner/dist/
+sdk/typescript/node_modules/
+sdk/typescript/dist/
+sdk/python/dist/
+sdk/python/*.egg-info/
+sdk/python/.pytest_cache/
+webapp/.next/
+*.log
+/tmp/selfship-local-secret
+.DS_Store

selfship_ai-0.1.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: selfship-ai
+Version: 0.1.0
+Summary: SelfShip LLM observability SDK — thin wrapper over Langfuse
+Project-URL: Homepage, https://selfship.ai
+Project-URL: Documentation, https://docs.selfship.ai
+Project-URL: Repository, https://github.com/selfship-ai/selfship
+Author-email: SelfShip <hello@selfship.ai>
+License: MIT
+Keywords: langfuse,llm,observability,selfship,tracing
+Classifier: Development Status :: 4 - Beta
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: langfuse<4,>=3
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-mock; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# selfship-ai
+
+Python SDK for [SelfShip](https://selfship.ai) — a thin wrapper over the Langfuse Python SDK.
+
+## Install
+
+```bash
+pip install selfship-ai
+```
+
+## Usage
+
+```python
+import selfship
+
+selfship.init()  # reads SELFSHIP_ORG_ID / SELFSHIP_ORG_SECRET
+
+interaction = selfship.begin(
+    user_id="user-123",
+    agent_name="support-bot",
+    input="Hello",
+)
+interaction.end(output="Hi there!", success=True)
+
+selfship.shutdown()
+```
+
+See [docs.selfship.ai](https://docs.selfship.ai/python/getting-started) for the full API.

selfship_ai-0.1.0/README.md

@@ -0,0 +1,28 @@
+# selfship-ai
+
+Python SDK for [SelfShip](https://selfship.ai) — a thin wrapper over the Langfuse Python SDK.
+
+## Install
+
+```bash
+pip install selfship-ai
+```
+
+## Usage
+
+```python
+import selfship
+
+selfship.init()  # reads SELFSHIP_ORG_ID / SELFSHIP_ORG_SECRET
+
+interaction = selfship.begin(
+    user_id="user-123",
+    agent_name="support-bot",
+    input="Hello",
+)
+interaction.end(output="Hi there!", success=True)
+
+selfship.shutdown()
+```
+
+See [docs.selfship.ai](https://docs.selfship.ai/python/getting-started) for the full API.

selfship_ai-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "selfship-ai"
+version = "0.1.0"
+description = "SelfShip LLM observability SDK — thin wrapper over Langfuse"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "SelfShip", email = "hello@selfship.ai" }]
+keywords = ["selfship", "langfuse", "llm", "observability", "tracing"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "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 :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["langfuse>=3,<4"]
+
+[project.urls]
+Homepage = "https://selfship.ai"
+Documentation = "https://docs.selfship.ai"
+Repository = "https://github.com/selfship-ai/selfship"
+
+[project.optional-dependencies]
+dev = ["build", "pytest", "pytest-mock"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/selfship"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

selfship_ai-0.1.0/src/selfship/__init__.py

@@ -0,0 +1,26 @@
+"""SelfShip Python SDK — thin wrapper over Langfuse."""
+
+from __future__ import annotations
+
+try:
+    from importlib.metadata import version as _pkg_version
+
+    __version__ = _pkg_version("selfship-ai")
+except Exception:  # pragma: no cover — editable/dev installs
+    from selfship._version import __version__
+
+from selfship._client import get_client, init, observe, shutdown
+from selfship._convenience import begin, identify, track
+from selfship._interaction import Interaction
+
+__all__ = [
+    "__version__",
+    "begin",
+    "get_client",
+    "identify",
+    "init",
+    "Interaction",
+    "observe",
+    "shutdown",
+    "track",
+]

selfship_ai-0.1.0/src/selfship/_client.py

@@ -0,0 +1,67 @@
+"""Langfuse client lifecycle for SelfShip."""
+
+from __future__ import annotations
+
+import atexit
+from typing import TYPE_CHECKING
+
+from langfuse import Langfuse
+from langfuse import get_client as _langfuse_get_client
+from langfuse import observe  # noqa: F401 — re-exported
+
+from selfship._config import SDK_VERSION_HEADER, resolve_credentials, resolve_endpoint
+from selfship._version import __version__
+
+if TYPE_CHECKING:
+    from langfuse import Langfuse as LangfuseClient
+
+_initialized = False
+_atexit_registered = False
+
+
+def init(
+    org_id: str | None = None,
+    org_secret: str | None = None,
+) -> LangfuseClient:
+    """Initialize the SelfShip SDK (wraps Langfuse with SelfShip credentials)."""
+    global _initialized, _atexit_registered
+
+    resolved_id, resolved_secret = resolve_credentials(org_id, org_secret)
+    endpoint = resolve_endpoint()
+
+    Langfuse(
+        public_key=resolved_id,
+        secret_key=resolved_secret,
+        host=endpoint,
+        media_upload_thread_count=0,
+        additional_headers={SDK_VERSION_HEADER: __version__},
+    )
+
+    _initialized = True
+
+    if not _atexit_registered:
+        atexit.register(shutdown)
+        _atexit_registered = True
+
+    return _langfuse_get_client()
+
+
+def get_client() -> LangfuseClient:
+    """Return the underlying Langfuse client."""
+    if not _initialized:
+        raise RuntimeError("SelfShip SDK not initialized. Call selfship.init() first.")
+    return _langfuse_get_client()
+
+
+def shutdown() -> None:
+    """Flush pending events and shut down the Langfuse client."""
+    if not _initialized:
+        return
+    _langfuse_get_client().shutdown()
+
+
+def reset_client_state() -> None:
+    """Reset module init flags (used in tests)."""
+    global _initialized, _atexit_registered
+    _initialized = False
+    _atexit_registered = False

selfship_ai-0.1.0/src/selfship/_config.py

@@ -0,0 +1,26 @@
+"""Configuration helpers for SelfShip SDK."""
+
+from __future__ import annotations
+
+import os
+
+DEFAULT_HOST = "https://otel.selfship.ai"
+SDK_VERSION_HEADER = "X-SelfShip-SDK-Version"
+
+
+def resolve_endpoint() -> str:
+    return os.environ.get("SELFSHIP_ENDPOINT", DEFAULT_HOST).rstrip("/")
+
+
+def resolve_credentials(
+    org_id: str | None,
+    org_secret: str | None,
+) -> tuple[str, str]:
+    resolved_id = org_id or os.environ.get("SELFSHIP_ORG_ID")
+    resolved_secret = org_secret or os.environ.get("SELFSHIP_ORG_SECRET")
+    if not resolved_id or not resolved_secret:
+        raise ValueError(
+            "SelfShip credentials required. Pass org_id/org_secret to init() "
+            "or set SELFSHIP_ORG_ID and SELFSHIP_ORG_SECRET."
+        )
+    return resolved_id, resolved_secret

selfship_ai-0.1.0/src/selfship/_convenience.py

@@ -0,0 +1,60 @@
+"""Convenience tracing API (begin, track, identify)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from selfship._client import get_client
+from selfship._identity import set_user_traits, user_metadata
+from selfship._interaction import Interaction
+
+
+def begin(
+    *,
+    user_id: str | None = None,
+    agent_name: str = "agent",
+    input: Any = None,
+    conversation_id: str | None = None,
+) -> Interaction:
+    """Open a timed interaction mapped to a Langfuse root span."""
+    client = get_client()
+    metadata = user_metadata(user_id)
+
+    span = client.start_span(name=agent_name, input=input, metadata=metadata or None)
+    client.update_current_trace(
+        user_id=user_id,
+        session_id=conversation_id,
+        input=input,
+        metadata=metadata or None,
+    )
+    return Interaction(span)
+
+
+def track(
+    *,
+    user_id: str | None = None,
+    input: Any = None,
+    output: Any = None,
+    agent_name: str = "agent",
+    conversation_id: str | None = None,
+) -> None:
+    """Fire-and-forget a single traced event."""
+    client = get_client()
+    metadata = user_metadata(user_id)
+
+    span = client.start_span(name=agent_name, input=input, metadata=metadata or None)
+    client.update_current_trace(
+        user_id=user_id,
+        session_id=conversation_id,
+        input=input,
+        output=output,
+        metadata=metadata or None,
+    )
+    if output is not None:
+        span.update(output=output)
+    span.end()
+
+
+def identify(user_id: str, traits: dict[str, Any]) -> None:
+    """Cache user metadata merged into subsequent traces for this user."""
+    set_user_traits(user_id, traits)

selfship_ai-0.1.0/src/selfship/_identity.py

@@ -0,0 +1,27 @@
+"""Client-side user trait cache for identify()."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_user_traits: dict[str, dict[str, Any]] = {}
+
+
+def set_user_traits(user_id: str, traits: dict[str, Any]) -> None:
+    existing = _user_traits.get(user_id, {})
+    existing.update(traits)
+    _user_traits[user_id] = existing
+
+
+def user_metadata(user_id: str | None) -> dict[str, Any]:
+    if not user_id:
+        return {}
+    traits = _user_traits.get(user_id)
+    if not traits:
+        return {}
+    return {"user": traits}
+
+
+def clear_user_traits() -> None:
+    """Reset cached traits (used in tests)."""
+    _user_traits.clear()

selfship_ai-0.1.0/src/selfship/_interaction.py

@@ -0,0 +1,37 @@
+"""Timed interaction handle returned by begin()."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class Interaction:
+    """A timed agent interaction mapped to a Langfuse root span."""
+
+    def __init__(self, span: Any) -> None:
+        self._span = span
+        self._metadata: dict[str, Any] = {}
+
+    def set_property(self, key: str, value: Any) -> None:
+        self._metadata[key] = value
+        self._span.update(metadata=dict(self._metadata))
+
+    def set_properties(self, properties: dict[str, Any]) -> None:
+        self._metadata.update(properties)
+        self._span.update(metadata=dict(self._metadata))
+
+    def end(
+        self,
+        output: Any = None,
+        *,
+        success: bool = True,
+    ) -> None:
+        update: dict[str, Any] = {}
+        if output is not None:
+            update["output"] = output
+        if not success:
+            update["level"] = "ERROR"
+            update["status_message"] = "Interaction failed"
+        if update:
+            self._span.update(**update)
+        self._span.end()

selfship_ai-0.1.0/src/selfship/_version.py

@@ -0,0 +1,3 @@
+"""Package version — keep in sync with pyproject.toml."""
+
+__version__ = "0.1.0"

selfship_ai-0.1.0/tests/conftest.py

@@ -0,0 +1,38 @@
+"""Shared pytest fixtures for selfship tests."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import selfship
+from selfship._client import reset_client_state
+from selfship._identity import clear_user_traits
+
+
+@pytest.fixture(autouse=True)
+def reset_state():
+    reset_client_state()
+    clear_user_traits()
+    yield
+    reset_client_state()
+    clear_user_traits()
+
+
+@pytest.fixture
+def mock_langfuse_client():
+    client = MagicMock()
+    span = MagicMock()
+    client.start_span.return_value = span
+    return client, span
+
+
+@pytest.fixture
+def initialized_sdk(mock_langfuse_client):
+    client, span = mock_langfuse_client
+    with patch("selfship._client.Langfuse", return_value=client), patch(
+        "selfship._client._langfuse_get_client", return_value=client
+    ):
+        selfship.init(org_id="org_test", org_secret="bps_test")
+        yield client, span

selfship_ai-0.1.0/tests/test_client.py

@@ -0,0 +1,72 @@
+"""Unit tests for selfship.init() and client lifecycle."""
+
+from __future__ import annotations
+
+import os
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+import selfship
+from selfship._config import SDK_VERSION_HEADER
+
+
+def test_init_with_explicit_credentials():
+    client = MagicMock()
+    with patch("selfship._client.Langfuse", return_value=client) as mock_ctor, patch(
+        "selfship._client._langfuse_get_client", return_value=client
+    ):
+        result = selfship.init(org_id="org_abc", org_secret="bps_secret")
+
+    mock_ctor.assert_called_once_with(
+        public_key="org_abc",
+        secret_key="bps_secret",
+        host="https://otel.selfship.ai",
+        media_upload_thread_count=0,
+        additional_headers={SDK_VERSION_HEADER: selfship.__version__},
+    )
+    assert result is client
+
+
+def test_init_reads_env_vars(monkeypatch):
+    monkeypatch.setenv("SELFSHIP_ORG_ID", "org_env")
+    monkeypatch.setenv("SELFSHIP_ORG_SECRET", "bps_env")
+    client = MagicMock()
+    with patch("selfship._client.Langfuse", return_value=client), patch(
+        "selfship._client._langfuse_get_client", return_value=client
+    ):
+        selfship.init()
+        assert selfship.get_client() is client
+
+
+def test_init_respects_selfship_endpoint(monkeypatch):
+    monkeypatch.setenv("SELFSHIP_ENDPOINT", "https://staging.otel.selfship.ai/")
+    client = MagicMock()
+    with patch("selfship._client.Langfuse", return_value=client) as mock_ctor, patch(
+        "selfship._client._langfuse_get_client", return_value=client
+    ):
+        selfship.init(org_id="org_abc", org_secret="bps_secret")
+
+    assert mock_ctor.call_args.kwargs["host"] == "https://staging.otel.selfship.ai"
+
+
+def test_init_missing_credentials_raises():
+    for key in ("SELFSHIP_ORG_ID", "SELFSHIP_ORG_SECRET"):
+        os.environ.pop(key, None)
+    with pytest.raises(ValueError, match="credentials required"):
+        selfship.init()
+
+
+def test_get_client_before_init_raises():
+    with pytest.raises(RuntimeError, match="not initialized"):
+        selfship.get_client()
+
+
+def test_shutdown_calls_langfuse_shutdown(initialized_sdk):
+    client, _ = initialized_sdk
+    selfship.shutdown()
+    client.shutdown.assert_called_once()
+
+
+def test_shutdown_before_init_is_noop():
+    selfship.shutdown()

selfship_ai-0.1.0/tests/test_convenience.py

@@ -0,0 +1,103 @@
+"""Unit tests for begin/end, track, and identify."""
+
+from __future__ import annotations
+
+import selfship
+
+
+def test_begin_maps_fields(initialized_sdk):
+    client, span = initialized_sdk
+
+    interaction = selfship.begin(
+        user_id="user-42",
+        agent_name="research-agent",
+        input="Summarize Q3",
+        conversation_id="conv-9f3a",
+    )
+
+    client.start_span.assert_called_once_with(
+        name="research-agent",
+        input="Summarize Q3",
+        metadata=None,
+    )
+    client.update_current_trace.assert_called_once_with(
+        user_id="user-42",
+        session_id="conv-9f3a",
+        input="Summarize Q3",
+        metadata=None,
+    )
+    assert interaction is not None
+
+
+def test_interaction_set_property_and_end(initialized_sdk):
+    _, span = initialized_sdk
+
+    interaction = selfship.begin(user_id="user-1", agent_name="bot", input="hi")
+    interaction.set_property("model", "gpt-4o")
+    interaction.set_properties({"temperature": 0.2})
+    interaction.end(output="done", success=True)
+
+    span.update.assert_any_call(metadata={"model": "gpt-4o"})
+    span.update.assert_any_call(metadata={"model": "gpt-4o", "temperature": 0.2})
+    span.update.assert_any_call(output="done")
+    span.end.assert_called_once()
+
+
+def test_interaction_end_failure_sets_error_level(initialized_sdk):
+    _, span = initialized_sdk
+
+    interaction = selfship.begin(agent_name="bot", input="hi")
+    interaction.end(output="failed", success=False)
+
+    span.update.assert_any_call(
+        output="failed",
+        level="ERROR",
+        status_message="Interaction failed",
+    )
+
+
+def test_track_one_shot_trace(initialized_sdk):
+    client, span = initialized_sdk
+
+    selfship.track(
+        user_id="user-42",
+        input="question",
+        output="answer",
+        agent_name="banking-bot",
+        conversation_id="conv-9f3a",
+    )
+
+    client.start_span.assert_called_once_with(
+        name="banking-bot",
+        input="question",
+        metadata=None,
+    )
+    client.update_current_trace.assert_called_once_with(
+        user_id="user-42",
+        session_id="conv-9f3a",
+        input="question",
+        output="answer",
+        metadata=None,
+    )
+    span.update.assert_called_once_with(output="answer")
+    span.end.assert_called_once()
+
+
+def test_identify_merges_into_begin_metadata(initialized_sdk):
+    client, span = initialized_sdk
+
+    selfship.identify("user-42", {"email": "alex@example.com", "plan": "pro"})
+    selfship.begin(user_id="user-42", agent_name="bot", input="hi")
+
+    expected_metadata = {"user": {"email": "alex@example.com", "plan": "pro"}}
+    client.start_span.assert_called_once_with(
+        name="bot",
+        input="hi",
+        metadata=expected_metadata,
+    )
+    client.update_current_trace.assert_called_once_with(
+        user_id="user-42",
+        session_id=None,
+        input="hi",
+        metadata=expected_metadata,
+    )

selfship_ai-0.1.0/tests/test_live_smoke.py

@@ -0,0 +1,26 @@
+"""Opt-in live smoke test against otel.selfship.ai."""
+
+from __future__ import annotations
+
+import os
+
+import pytest
+
+import selfship
+
+HAS_LIVE_CREDS = bool(
+    os.environ.get("SELFSHIP_ORG_ID") and os.environ.get("SELFSHIP_ORG_SECRET")
+)
+
+
+@pytest.mark.skipif(not HAS_LIVE_CREDS, reason="SELFSHIP_ORG_ID/SELFSHIP_ORG_SECRET not set")
+def test_live_trace_smoke():
+    """Send a real trace to the SelfShip gateway."""
+    selfship.init()
+    interaction = selfship.begin(
+        user_id="sdk-smoke-test",
+        agent_name="sdk-python-smoke",
+        input="ping",
+    )
+    interaction.end(output="pong", success=True)
+    selfship.shutdown()