memoturn 0.1.0__tar.gz

memoturn-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+node_modules/
+dist/
+.next/
+.turbo/
+coverage/
+*.tsbuildinfo
+
+# env
+.env
+.env.local
+.env.*.local
+
+# os / editor
+.DS_Store
+*.log
+
+# claude code — personal/local settings (team config is .claude/settings.json)
+.claude/settings.local.json
+
+# prisma
+packages/db/prisma/*.db
+# generated by the TanStack Router plugin
+**/routeTree.gen.ts
+
+# python
+__pycache__/
+*.egg-info/
+.venv/
+sdks/python/dist/
+
+# playwright (e2e)
+**/playwright-report/
+**/test-results/
+**/.playwright/

memoturn-0.1.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: memoturn
+Version: 0.1.0
+Summary: memoturn Python SDK — tracing, @observe, OpenAI wrapper, prompts.
+Project-URL: Homepage, https://github.com/memoturn/memoturn
+Project-URL: Repository, https://github.com/memoturn/memoturn
+Project-URL: Issues, https://github.com/memoturn/memoturn/issues
+License: Apache-2.0
+Keywords: evals,langchain,llm,memoturn,observability,openai,opentelemetry,tracing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# memoturn Python SDK
+
+Tracing, prompts, and the OpenAI wrapper for [memoturn](https://github.com/memoturn/memoturn).
+Stdlib-only (no required dependencies).
+
+```bash
+pip install memoturn        # or: uv add memoturn
+```
+
+## Trace with the decorator
+
+```python
+from memoturn import Memoturn, configure, observe
+
+configure(Memoturn(base_url="http://localhost:3001", public_key="pk-...", secret_key="sk-..."))
+
+@observe()
+def retrieve(q): ...
+
+@observe(as_type="generation")
+def answer(q, docs): ...
+
+@observe(name="rag-pipeline")
+def rag(q):
+    return answer(q, retrieve(q))   # nested spans under one trace
+```
+
+The outermost `@observe` opens a trace; nested calls become child spans (a waterfall in
+the console). Env vars `MEMOTURN_BASE_URL` / `MEMOTURN_PUBLIC_KEY` / `MEMOTURN_SECRET_KEY`
+are used when not passed explicitly.
+
+## Low-level API
+
+```python
+mt = Memoturn()
+trace = mt.trace(name="chat", user_id="u1")
+gen = trace.generation(name="answer", model="claude-sonnet-4-6", input=messages)
+gen.end(output=reply, usage={"promptTokens": 100, "completionTokens": 20})
+trace.score("user-feedback", value=1, comment="helpful")
+mt.shutdown()  # flush
+```
+
+## OpenAI wrapper
+
+```python
+from openai import OpenAI
+from memoturn import wrap_openai
+
+client = wrap_openai(OpenAI())
+client.chat.completions.create(model="gpt-4o-mini", messages=[...])  # recorded automatically
+```
+
+## Prompts
+
+```python
+from memoturn import get_prompt, compile_prompt
+
+prompt = get_prompt("support-reply", channel="production")
+messages = compile_prompt(prompt, product="memoturn", question="How do I trace a call?")
+```

memoturn-0.1.0/README.md

@@ -0,0 +1,60 @@
+# memoturn Python SDK
+
+Tracing, prompts, and the OpenAI wrapper for [memoturn](https://github.com/memoturn/memoturn).
+Stdlib-only (no required dependencies).
+
+```bash
+pip install memoturn        # or: uv add memoturn
+```
+
+## Trace with the decorator
+
+```python
+from memoturn import Memoturn, configure, observe
+
+configure(Memoturn(base_url="http://localhost:3001", public_key="pk-...", secret_key="sk-..."))
+
+@observe()
+def retrieve(q): ...
+
+@observe(as_type="generation")
+def answer(q, docs): ...
+
+@observe(name="rag-pipeline")
+def rag(q):
+    return answer(q, retrieve(q))   # nested spans under one trace
+```
+
+The outermost `@observe` opens a trace; nested calls become child spans (a waterfall in
+the console). Env vars `MEMOTURN_BASE_URL` / `MEMOTURN_PUBLIC_KEY` / `MEMOTURN_SECRET_KEY`
+are used when not passed explicitly.
+
+## Low-level API
+
+```python
+mt = Memoturn()
+trace = mt.trace(name="chat", user_id="u1")
+gen = trace.generation(name="answer", model="claude-sonnet-4-6", input=messages)
+gen.end(output=reply, usage={"promptTokens": 100, "completionTokens": 20})
+trace.score("user-feedback", value=1, comment="helpful")
+mt.shutdown()  # flush
+```
+
+## OpenAI wrapper
+
+```python
+from openai import OpenAI
+from memoturn import wrap_openai
+
+client = wrap_openai(OpenAI())
+client.chat.completions.create(model="gpt-4o-mini", messages=[...])  # recorded automatically
+```
+
+## Prompts
+
+```python
+from memoturn import get_prompt, compile_prompt
+
+prompt = get_prompt("support-reply", channel="production")
+messages = compile_prompt(prompt, product="memoturn", question="How do I trace a call?")
+```

memoturn-0.1.0/examples/quickstart.py

@@ -0,0 +1,44 @@
+"""Emit a trace from Python end-to-end. Run after `bun run dev` + `bun run seed`:
+
+    cd sdks/python && uv run examples/quickstart.py
+"""
+import os
+import time
+
+from memoturn import Memoturn, configure, observe
+
+configure(
+    Memoturn(
+        base_url=os.environ.get("MEMOTURN_BASE_URL", "http://localhost:3001"),
+        public_key=os.environ.get("MEMOTURN_PUBLIC_KEY", "pk-mt-dev"),
+        secret_key=os.environ.get("MEMOTURN_SECRET_KEY", "sk-mt-dev"),
+    )
+)
+
+
+@observe()
+def retrieve(query: str) -> list[str]:
+    time.sleep(0.02)
+    return ["memoturn is an open-source AI engineering platform."]
+
+
+@observe(as_type="generation")
+def answer(question: str, docs: list[str]) -> str:
+    time.sleep(0.05)
+    return "memoturn is an open-source AI engineering platform."
+
+
+@observe(name="rag-pipeline")
+def rag(question: str) -> str:
+    docs = retrieve(question)
+    return answer(question, docs)
+
+
+if __name__ == "__main__":
+    from memoturn import get_client
+
+    result = rag("What is memoturn?")
+    get_client().shutdown()  # flush
+    print("answer:", result)
+    print("emitted a nested trace (rag-pipeline → retrieve, answer)")
+    print("  open the console Traces view to see the waterfall")

memoturn-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "memoturn"
+version = "0.1.0"
+description = "memoturn Python SDK — tracing, @observe, OpenAI wrapper, prompts."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "Apache-2.0" }
+keywords = ["memoturn", "llm", "observability", "tracing", "openai", "langchain", "evals", "opentelemetry"]
+dependencies = []
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: Apache Software License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/memoturn/memoturn"
+Repository = "https://github.com/memoturn/memoturn"
+Issues = "https://github.com/memoturn/memoturn/issues"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/memoturn"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

memoturn-0.1.0/src/memoturn/__init__.py

@@ -0,0 +1,19 @@
+"""memoturn Python SDK — LLM observability, prompts, and evals."""
+from .client import Memoturn, Span, Trace
+from .decorator import configure, get_client, observe
+from .openai import wrap_openai
+from .prompt import compile_prompt, get_prompt
+
+__all__ = [
+    "Memoturn",
+    "Trace",
+    "Span",
+    "observe",
+    "configure",
+    "get_client",
+    "get_prompt",
+    "compile_prompt",
+    "wrap_openai",
+]
+
+__version__ = "0.1.0"

memoturn-0.1.0/src/memoturn/client.py

@@ -0,0 +1,152 @@
+"""memoturn client — batches events and flushes to POST /v1/ingest.
+
+Stdlib-only (urllib). Create trace/span/generation handles and call .end() as work
+completes; the client handles ids, timestamps, batching, and Basic auth.
+"""
+from __future__ import annotations
+
+import atexit
+import base64
+import datetime as _dt
+import json
+import os
+import threading
+import urllib.error
+import urllib.request
+import uuid
+from typing import Any, Optional
+
+
+def _id() -> str:
+    return str(uuid.uuid4())
+
+
+def _now() -> str:
+    # ISO-8601 with millisecond precision + 'Z', matching the JS SDK.
+    return _dt.datetime.now(_dt.timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+class Memoturn:
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        public_key: Optional[str] = None,
+        secret_key: Optional[str] = None,
+        environment: Optional[str] = None,
+        flush_at: int = 20,
+    ) -> None:
+        self.base_url = (base_url or os.environ.get("MEMOTURN_BASE_URL", "http://localhost:3001")).rstrip("/")
+        self.public_key = public_key or os.environ.get("MEMOTURN_PUBLIC_KEY", "")
+        self.secret_key = secret_key or os.environ.get("MEMOTURN_SECRET_KEY", "")
+        self.environment = environment or os.environ.get("MEMOTURN_ENVIRONMENT", "default")
+        self.flush_at = flush_at
+        self._buffer: list[dict[str, Any]] = []
+        self._lock = threading.Lock()
+        atexit.register(self.flush)
+
+    # ── public API ────────────────────────────────────────────────────────────
+    def trace(self, **body: Any) -> "Trace":
+        tid = body.pop("id", None) or _id()
+        body.setdefault("environment", self.environment)
+        self._enqueue("trace-create", {**body, "id": tid})
+        return Trace(self, tid)
+
+    def flush(self) -> None:
+        with self._lock:
+            batch, self._buffer = self._buffer, []
+        if not batch:
+            return
+        auth = base64.b64encode(f"{self.public_key}:{self.secret_key}".encode()).decode()
+        req = urllib.request.Request(
+            f"{self.base_url}/v1/ingest",
+            data=json.dumps({"batch": batch}, default=str).encode(),
+            headers={"content-type": "application/json", "authorization": f"Basic {auth}"},
+            method="POST",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=10).read()
+        except urllib.error.HTTPError as e:
+            if e.code != 207:
+                with self._lock:
+                    self._buffer[0:0] = batch  # re-buffer for next flush
+                raise
+
+    def shutdown(self) -> None:
+        self.flush()
+
+    # ── internal ──────────────────────────────────────────────────────────────
+    def _enqueue(self, type_: str, body: dict[str, Any]) -> None:
+        with self._lock:
+            self._buffer.append({"id": _id(), "type": type_, "timestamp": _now(), "body": body})
+            should = len(self._buffer) >= self.flush_at
+        if should:
+            self.flush()
+
+
+class Trace:
+    def __init__(self, client: Memoturn, trace_id: str) -> None:
+        self._c = client
+        self.id = trace_id
+
+    def update(self, **body: Any) -> "Trace":
+        self._c._enqueue("trace-create", {**body, "id": self.id, "environment": self._c.environment})
+        return self
+
+    def span(self, **body: Any) -> "Span":
+        return self._observe("span-create", "span", body)
+
+    def generation(self, **body: Any) -> "Span":
+        return self._observe("generation-create", "generation", body)
+
+    def event(self, **body: Any) -> None:
+        self._c._enqueue(
+            "event-create",
+            {**body, "id": body.pop("id", None) or _id(), "traceId": self.id,
+             "environment": self._c.environment, "startTime": _now()},
+        )
+
+    def score(self, name: str, value: Optional[float] = None, **body: Any) -> "Trace":
+        self._c._enqueue(
+            "score-create",
+            {"id": _id(), "traceId": self.id, "name": name, "value": value,
+             "environment": self._c.environment, **body},
+        )
+        return self
+
+    def _observe(self, type_: str, kind: str, body: dict[str, Any]) -> "Span":
+        oid = body.pop("id", None) or _id()
+        self._c._enqueue(
+            type_,
+            {**body, "id": oid, "traceId": self.id, "environment": self._c.environment, "startTime": _now()},
+        )
+        return Span(self._c, self.id, oid, kind)
+
+
+class Span:
+    def __init__(self, client: Memoturn, trace_id: str, obs_id: str, kind: str) -> None:
+        self._c = client
+        self._trace_id = trace_id
+        self.id = obs_id
+        self._kind = kind
+
+    def span(self, **body: Any) -> "Span":
+        return self._child("span-create", "span", body)
+
+    def generation(self, **body: Any) -> "Span":
+        return self._child("generation-create", "generation", body)
+
+    def _child(self, type_: str, kind: str, body: dict[str, Any]) -> "Span":
+        oid = body.pop("id", None) or _id()
+        self._c._enqueue(
+            type_,
+            {**body, "id": oid, "traceId": self._trace_id, "parentObservationId": self.id,
+             "environment": self._c.environment, "startTime": _now()},
+        )
+        return Span(self._c, self._trace_id, oid, kind)
+
+    def end(self, **body: Any) -> None:
+        type_ = "generation-update" if self._kind == "generation" else "span-update"
+        self._c._enqueue(
+            type_,
+            {**body, "id": self.id, "traceId": self._trace_id, "environment": self._c.environment, "endTime": _now()},
+        )

memoturn-0.1.0/src/memoturn/decorator.py

@@ -0,0 +1,87 @@
+"""@observe decorator — trace any function with automatic nesting.
+
+The outermost @observe creates a trace + root observation; nested @observe calls become
+child spans. Uses a contextvar so nesting works across sync and async call stacks.
+"""
+from __future__ import annotations
+
+import contextvars
+import functools
+import inspect
+from typing import Any, Callable, Optional
+
+from .client import Memoturn, Span, Trace
+
+_default: Optional[Memoturn] = None
+_ctx: contextvars.ContextVar[Optional[tuple[Trace, Span]]] = contextvars.ContextVar("memoturn_ctx", default=None)
+
+
+def configure(client: Memoturn) -> Memoturn:
+    """Set the default client used by @observe (and returned by get_client)."""
+    global _default
+    _default = client
+    return client
+
+
+def get_client() -> Memoturn:
+    global _default
+    if _default is None:
+        _default = Memoturn()
+    return _default
+
+
+def _begin(name: str, as_type: str, inp: Any) -> tuple[Trace, Span, Any]:
+    client = get_client()
+    cur = _ctx.get()
+    if cur is None:
+        trace = client.trace(name=name, input=inp)
+        span = trace.generation(name=name, input=inp) if as_type == "generation" else trace.span(name=name, input=inp)
+    else:
+        trace, parent = cur
+        span = parent.generation(name=name, input=inp) if as_type == "generation" else parent.span(name=name, input=inp)
+    token = _ctx.set((trace, span))
+    return trace, span, (token, cur is None)
+
+
+def _finish(trace: Trace, span: Span, state: Any, output: Any) -> None:
+    token, is_root = state
+    span.end(output=output)
+    if is_root:
+        trace.update(output=output)
+    _ctx.reset(token)
+
+
+def observe(_fn: Optional[Callable] = None, *, name: Optional[str] = None, as_type: str = "span") -> Callable:
+    def deco(fn: Callable) -> Callable:
+        obs_name = name or fn.__name__
+
+        if inspect.iscoroutinefunction(fn):
+            @functools.wraps(fn)
+            async def awrapper(*args: Any, **kwargs: Any) -> Any:
+                trace, span, state = _begin(obs_name, as_type, {"args": args, "kwargs": kwargs})
+                try:
+                    out = await fn(*args, **kwargs)
+                    _finish(trace, span, state, out)
+                    return out
+                except Exception as e:  # noqa: BLE001
+                    span.end(level="ERROR", statusMessage=str(e))
+                    _ctx.reset(state[0])
+                    raise
+
+            return awrapper
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            trace, span, state = _begin(obs_name, as_type, {"args": args, "kwargs": kwargs})
+            try:
+                out = fn(*args, **kwargs)
+                _finish(trace, span, state, out)
+                return out
+            except Exception as e:  # noqa: BLE001
+                span.end(level="ERROR", statusMessage=str(e))
+                _ctx.reset(state[0])
+                raise
+
+        return wrapper
+
+    return deco(_fn) if callable(_fn) else deco

memoturn-0.1.0/src/memoturn/langchain.py

@@ -0,0 +1,89 @@
+"""LangChain callback handler — records chains, LLM calls, and tools as a trace tree.
+
+Pass an instance in ``callbacks=[...]``:
+
+    from memoturn.langchain import MemoturnCallbackHandler
+    chain.invoke(input, config={"callbacks": [MemoturnCallbackHandler()]})
+
+Implemented without importing langchain (duck-typed) so the SDK has no hard dependency;
+LangChain invokes these methods by name at runtime.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+from uuid import UUID
+
+from .client import Memoturn, Span, Trace
+from .decorator import get_client
+
+
+class MemoturnCallbackHandler:
+    # LangChain reads these attributes off the handler.
+    raise_error = False
+    run_inline = True
+
+    def __init__(self, client: Optional[Memoturn] = None, trace_name: str = "langchain") -> None:
+        self._c = client or get_client()
+        self._trace_name = trace_name
+        self._trace: Optional[Trace] = None
+        self._spans: dict[str, Span] = {}
+
+    def _ensure_trace(self) -> Trace:
+        if self._trace is None:
+            self._trace = self._c.trace(name=self._trace_name)
+        return self._trace
+
+    # ── chains ──────────────────────────────────────────────────────────────
+    def on_chain_start(self, serialized: Any, inputs: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._spans[str(run_id)] = self._ensure_trace().span(name="chain", input=inputs)
+
+    def on_chain_end(self, outputs: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, output=outputs)
+
+    def on_chain_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, level="ERROR", statusMessage=str(error))
+
+    # ── LLMs ────────────────────────────────────────────────────────────────
+    def on_llm_start(self, serialized: Any, prompts: list[str], *, run_id: UUID, **kwargs: Any) -> None:
+        model = (kwargs.get("invocation_params") or {}).get("model") or (serialized or {}).get("name")
+        self._spans[str(run_id)] = self._ensure_trace().generation(name="llm", model=model, input=prompts)
+
+    def on_chat_model_start(self, serialized: Any, messages: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        model = (kwargs.get("invocation_params") or {}).get("model") or (serialized or {}).get("name")
+        self._spans[str(run_id)] = self._ensure_trace().generation(name="chat", model=model, input=messages)
+
+    def on_llm_end(self, response: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        usage = None
+        try:
+            tu = (response.llm_output or {}).get("token_usage") or {}
+            usage = {
+                "promptTokens": tu.get("prompt_tokens"),
+                "completionTokens": tu.get("completion_tokens"),
+                "totalTokens": tu.get("total_tokens"),
+            }
+        except Exception:  # noqa: BLE001
+            pass
+        self._end(run_id, output=getattr(response, "generations", response), usage=usage)
+
+    def on_llm_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, level="ERROR", statusMessage=str(error))
+
+    # ── tools ───────────────────────────────────────────────────────────────
+    def on_tool_start(self, serialized: Any, input_str: str, *, run_id: UUID, **kwargs: Any) -> None:
+        name = (serialized or {}).get("name", "tool")
+        self._spans[str(run_id)] = self._ensure_trace().span(name=name, input=input_str)
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, output=output)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        self._end(run_id, level="ERROR", statusMessage=str(error))
+
+    # ── helpers ─────────────────────────────────────────────────────────────
+    def _end(self, run_id: UUID, **body: Any) -> None:
+        span = self._spans.pop(str(run_id), None)
+        if span is not None:
+            span.end(**{k: v for k, v in body.items() if v is not None})
+
+    def flush(self) -> None:
+        self._c.flush()

memoturn-0.1.0/src/memoturn/openai.py

@@ -0,0 +1,51 @@
+"""Drop-in OpenAI wrapper — records each chat completion as a memoturn generation."""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .client import Memoturn, Trace
+from .decorator import get_client
+
+
+def wrap_openai(client: Any, memoturn: Optional[Memoturn] = None, *, trace: Optional[Trace] = None) -> Any:
+    """Patch ``client.chat.completions.create`` to trace calls. Returns the same client."""
+    mt = memoturn or get_client()
+    completions = client.chat.completions
+    original = completions.create
+
+    def create(*args: Any, **kwargs: Any) -> Any:
+        t = trace or mt.trace(name="openai.chat")
+        gen = t.generation(
+            name="openai.chat.completions",
+            model=kwargs.get("model"),
+            provider="openai",
+            input=kwargs.get("messages"),
+            modelParameters={k: v for k, v in kwargs.items() if k not in ("model", "messages")},
+        )
+        try:
+            resp = original(*args, **kwargs)
+            usage = getattr(resp, "usage", None)
+            gen.end(
+                output=_message(resp),
+                usage={
+                    "promptTokens": getattr(usage, "prompt_tokens", None),
+                    "completionTokens": getattr(usage, "completion_tokens", None),
+                    "totalTokens": getattr(usage, "total_tokens", None),
+                }
+                if usage
+                else None,
+            )
+            return resp
+        except Exception as e:  # noqa: BLE001
+            gen.end(level="ERROR", statusMessage=str(e))
+            raise
+
+    completions.create = create  # type: ignore[assignment]
+    return client
+
+
+def _message(resp: Any) -> Any:
+    try:
+        return resp.choices[0].message.model_dump()
+    except Exception:  # noqa: BLE001
+        return str(resp)