generalcontext 0.2.0__py3-none-any.whl

generalcontext/__init__.py

@@ -0,0 +1,807 @@
+# Copyright 2026 General Context Labs, Inc.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Record your agent's model calls for General Context, without changing how it runs.
+
+    import generalcontext
+    generalcontext.initialize()            # once per process, reads GENERALCONTEXT_API_KEY
+
+    with generalcontext.session(conversation_id, user_id="u_42"):
+        client.chat.completions.create(...)   # any OpenAI or Anthropic client, anywhere
+
+`initialize()` patches the installed `openai` and `anthropic` client classes, so every
+client is recorded: chat.completions, responses and messages, sync and async, streamed or
+not. Raw `httpx` and `requests` POSTs to `/chat/completions` are recorded only with
+`instrument_http=True`. Calls are sent from a background thread. Your agent never waits on
+General Context, and a failure on our side is logged and dropped, never raised.
+
+`redact=True` replaces emails, phone numbers and card or SSN-like numbers with stable
+placeholders (<phone:3f2a1c>) before anything leaves this process. Set
+GENERALCONTEXT_REDACT_SALT to one secret in every process so placeholders match.
+
+Standard library only. `wrap(client)` and `conversation(...)` from 0.1 still work.
+"""
+
+from contextlib import contextmanager
+from contextvars import ContextVar
+from datetime import datetime, timezone
+import atexit
+import functools
+import hashlib
+import hmac
+import inspect
+import json
+import logging
+import os
+import queue
+import re
+import threading
+import time
+import urllib.parse
+import urllib.request
+import uuid
+
+__all__ = ["initialize", "session", "with_session", "conversation", "task", "flush",
+           "report_outcome", "log_event", "wrap"]
+__version__ = "0.2.0"
+
+DEFAULT_BASE_URL = "https://generalcontextlabs.com"
+BATCH = 20
+log = logging.getLogger("generalcontext")
+
+_session = ContextVar("generalcontext_session", default=None)
+_task = ContextVar("generalcontext_task", default=None)
+# Set while a patched SDK call runs, so the call is recorded once even when it is wrapped
+# twice or its HTTP request passes through a patched transport.
+_inside = ContextVar("generalcontext_inside", default=False)
+
+_config = {"initialized": False, "api_key": None, "base_url": None, "app": None, "scrub": None, "batch": BATCH,
+           "before_send": None}
+
+
+def _api_key():
+    return _config["api_key"] or os.environ.get("GENERALCONTEXT_API_KEY")
+
+
+def _base_url():
+    return (_config["base_url"] or os.environ.get("GENERALCONTEXT_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat()
+
+
+def _disabled():
+    """GENERALCONTEXT_DISABLED=1 turns the SDK off without a code change."""
+    return os.environ.get("GENERALCONTEXT_DISABLED", "").strip().lower() in ("1", "true", "yes")
+
+
+# ---- Setup -------------------------------------------------------------------------------
+
+def initialize(api_key=None, base_url=None, app_name=None, redact=False, before_send=None,
+               instrument_http=False, disable_batch=False):
+    """Record every OpenAI and Anthropic call in this process. Call once, in every process.
+
+    SDK clients are always recorded. Raw httpx/requests POSTs to /chat/completions are
+    recorded only with instrument_http=True. before_send(call) runs on the sender thread and
+    returns the dict to send, or None to drop the call.
+    """
+    if _disabled():
+        log.info("GENERALCONTEXT_DISABLED is set; General Context is off")
+        return
+    if _config["initialized"]:
+        log.warning("generalcontext.initialize() was already called; this call is ignored")
+        return
+    _config.update(initialized=True, api_key=api_key, base_url=base_url, app=app_name,
+                   scrub=_redactor(redact), before_send=before_send, batch=1 if disable_batch else BATCH)
+    if not _api_key():
+        log.warning("GENERALCONTEXT_API_KEY is not set; model calls will not be recorded")
+    if not _secure(_base_url()):
+        _warn_insecure()
+    atexit.register(_flush_at_exit)
+    _patch_sdks()
+    if instrument_http:
+        _patch_http()
+
+
+def _patch_sdks():
+    targets = [
+        ("openai.resources.chat.completions", "Completions", "AsyncCompletions", "openai-chat"),
+        ("openai.resources.responses", "Responses", "AsyncResponses", "openai-responses"),
+        ("anthropic.resources.messages", "Messages", "AsyncMessages", "anthropic"),
+    ]
+    for module_name, sync_name, async_name, api in targets:
+        try:
+            module = __import__(module_name, fromlist=[sync_name])
+        except Exception:
+            continue  # Package not installed.
+        for name, is_async in ((sync_name, False), (async_name, True)):
+            cls = getattr(module, name, None)
+            if cls is None or getattr(cls.create, "_generalcontext", False):
+                continue
+            cls.create = _recording(cls.create, api, is_async)
+            if api == "anthropic" and hasattr(cls, "stream"):
+                cls.stream = _recording_stream_manager(cls.stream, is_async)
+
+
+def wrap(client, *, redact=False):
+    """Record every model call `client` makes. Returns the same client. Prefer initialize()."""
+    if _disabled():
+        return client
+    scrub = _redactor(redact)
+    targets = []
+    if hasattr(client, "chat") and hasattr(getattr(client.chat, "completions", None), "create"):
+        targets.append((client.chat.completions, "openai-chat"))
+    if hasattr(getattr(client, "responses", None), "create"):
+        targets.append((client.responses, "openai-responses"))
+    if hasattr(getattr(client, "messages", None), "create") and not hasattr(client, "chat"):
+        targets.append((client.messages, "anthropic"))
+    if not targets:
+        raise TypeError("generalcontext.wrap expects an OpenAI or Anthropic client")
+    for owner, api in targets:
+        create = owner.create
+        if not getattr(create, "_generalcontext_instance", False):
+            owner.create = _recording(create, api, inspect.iscoroutinefunction(inspect.unwrap(create)), scrub)
+            owner.create._generalcontext_instance = True
+    return client
+
+
+# ---- Sessions and tasks --------------------------------------------------------------------
+
+@contextmanager
+def session(session_id, user_id=None, channel=None, product=None, metadata=None):
+    """Tag every call inside the block as part of conversation `session_id`. Safe across threads and asyncio."""
+    tags = {key: value for key, value in dict(id=str(session_id), user_id=user_id, channel=channel,
+                                               product=product, metadata=metadata).items() if value is not None}
+    token = _session.set(tags)
+    try:
+        yield
+    finally:
+        _session.reset(token)
+
+
+with_session = session
+conversation = session
+
+
+@contextmanager
+def task(name):
+    """Mark every call inside the block as part of the unit of work `name`."""
+    token = _task.set(str(name))
+    try:
+        yield
+    finally:
+        _task.reset(token)
+
+
+# ---- Sending -----------------------------------------------------------------------------
+
+MAX_CALL_BYTES = 4_000_000     # The server rejects larger calls.
+MAX_QUEUE_BYTES = 64_000_000
+MAX_BATCH_BYTES = 4_000_000
+MAX_QUEUE_CALLS = 5000
+_warned_at = {}
+
+
+def _warn(key, message, *args):
+    """Log `message` at most once per 60 seconds per `key`."""
+    now = time.monotonic()
+    if now - _warned_at.get(key, -1e9) >= 60:
+        _warned_at[key] = now
+        log.warning(message, *args)
+
+
+def _secure(url):
+    """HTTPS, or plain HTTP to this machine for local development."""
+    parts = urllib.parse.urlsplit(url)
+    return parts.scheme == "https" or (parts.scheme == "http" and parts.hostname in ("localhost", "127.0.0.1", "::1"))
+
+
+def _warn_insecure():
+    _warn("http", "General Context base_url %s is not https; nothing will be sent", _base_url())
+
+
+def _size(value, limit):
+    """Cheap size estimate of a snapshot; stops counting past `limit`."""
+    total, stack = 0, [value]
+    while stack and total <= limit:
+        item = stack.pop()
+        total += 8
+        if isinstance(item, str):
+            total += len(item)
+        elif isinstance(item, dict):
+            stack.extend(item.keys())
+            stack.extend(item.values())
+        elif isinstance(item, list):
+            stack.extend(item)
+    return total
+
+
+class _Sender:
+    """One daemon thread that redacts, encodes, batches and posts recorded calls."""
+
+    def __init__(self):
+        self._reset()
+        self.warned = False
+
+    def _reset(self):
+        # Also run in a forked child: the parent's thread and lock do not exist there.
+        self.queue = queue.Queue(maxsize=MAX_QUEUE_CALLS)
+        self.lock = threading.Lock()
+        self.bytes = 0
+        self.thread = None
+
+    def put(self, call, scrub):
+        """Runs on the caller's thread, so it only measures and enqueues."""
+        if not _api_key():
+            if not self.warned:
+                log.warning("GENERALCONTEXT_API_KEY is not set; model calls are not recorded")
+                self.warned = True
+            return
+        if not _secure(_base_url()):
+            return _warn_insecure()
+        size = _size(call, MAX_CALL_BYTES)
+        if size > MAX_CALL_BYTES:
+            return _warn("oversized", "General Context dropped a model call larger than %d bytes", MAX_CALL_BYTES)
+        with self.lock:
+            if self.bytes + size > MAX_QUEUE_BYTES:
+                return _warn("full", "General Context queue is full; a model call was dropped")
+            try:
+                self.queue.put_nowait((call, scrub, size))
+            except queue.Full:
+                return _warn("full", "General Context queue is full; a model call was dropped")
+            self.bytes += size
+            if self.thread is None or not self.thread.is_alive():
+                self.thread = threading.Thread(target=self._run, name="generalcontext", daemon=True)
+                self.thread.start()
+
+    def _take(self, pending, timeout):
+        """Move one call from the queue into `pending` as JSON bytes. False when the queue stayed empty."""
+        try:
+            call, scrub, size = self.queue.get(timeout=timeout)
+        except queue.Empty:
+            return False
+        with self.lock:
+            self.bytes -= size
+        data = _encode(call, scrub)
+        if data is None:
+            self.queue.task_done()
+        else:
+            pending.append(data)
+        return True
+
+    def _run(self):
+        pending = []  # Encoded calls taken from the queue; each still owes one task_done.
+        while True:
+            if not pending:
+                self._take(pending, None)
+                continue
+            while (len(pending) < _config["batch"] and sum(map(len, pending)) < MAX_BATCH_BYTES
+                   and self._take(pending, 0.5)):
+                pass
+            count, size = 0, 0
+            for data in pending:
+                if count and (count >= _config["batch"] or size + len(data) + 1 > MAX_BATCH_BYTES):
+                    break
+                count, size = count + 1, size + len(data) + 1
+            batch, pending = pending[:count], pending[count:]
+            try:
+                head = json.dumps({"sdk": f"python/{__version__}", "app": _config["app"]})[:-1]
+                _post("/api/platform-collect/sdk", (head + ', "calls": [').encode() + b",".join(batch) + b"]}", 15)
+            except Exception as error:  # Never let our failure reach the agent.
+                _warn("send", "General Context did not accept %d calls: %s", len(batch), error)
+            finally:
+                for _ in batch:
+                    self.queue.task_done()
+
+
+def _encode(call, scrub):
+    """before_send, redaction and JSON encoding, on the sender thread. None drops the call."""
+    try:
+        before_send = _config["before_send"]
+        if before_send is not None:
+            try:
+                call = before_send(call)
+            except Exception as error:
+                _warn("before_send", "General Context before_send raised; a call was dropped: %s", error)
+                return None
+            if call is None:
+                return None
+        data = json.dumps(_scrubbed(call, scrub), default=str).encode()
+    except Exception as error:
+        _warn("encode", "General Context could not encode a model call: %s", error)
+        return None
+    if len(data) > MAX_CALL_BYTES:
+        _warn("oversized", "General Context dropped a model call larger than %d bytes", MAX_CALL_BYTES)
+        return None
+    return data
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Refuse redirects, so the Authorization header is never forwarded anywhere else."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None  # urllib then raises HTTPError for the 3xx.
+
+
+_opener = urllib.request.build_opener(_NoRedirect)  # Honors HTTPS_PROXY and SSL_CERT_FILE.
+
+
+def _post(path, body, timeout):
+    url = _base_url() + path
+    if not _secure(url):
+        _warn_insecure()
+        raise ValueError("refusing to send to a non-https base_url")
+    data = body if isinstance(body, bytes) else json.dumps(body, default=str).encode()
+    request = urllib.request.Request(url, data=data, headers={
+        "Authorization": "Bearer " + (_api_key() or ""), "Content-Type": "application/json"})
+    with _opener.open(request, timeout=timeout) as response:
+        response.read()
+
+
+_sender = _Sender()
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_sender._reset)
+
+
+def flush(timeout=10):
+    """Wait until recorded calls are sent. Call before a short-lived process exits. True if all were sent."""
+    try:
+        done = threading.Event()
+        threading.Thread(target=lambda: (_sender.queue.join(), done.set()), daemon=True).start()
+        return done.wait(timeout)
+    except Exception as error:
+        log.warning("General Context flush failed: %s", error)
+        return False
+
+
+def _flush_at_exit():
+    try:
+        flush(2)
+    except Exception:
+        pass
+
+
+def _send_after_flush(path, body, what):
+    """Flush first, so the conversation exists when the server receives `body`."""
+    try:
+        if not _api_key():
+            return False
+        flush()
+        _post(path, body, 10)
+        return True
+    except Exception as error:
+        log.warning("General Context did not accept the %s: %s", what, error)
+        return False
+
+
+def _scrub_text(value):
+    scrub = _config["scrub"]
+    return scrub(value) if scrub is not None and isinstance(value, str) else value
+
+
+def report_outcome(session_id, outcome, note=None):
+    """Mark a conversation as a success or a failure. True if General Context accepted it."""
+    try:
+        if outcome not in ("success", "fail"):
+            log.warning("report_outcome expects 'success' or 'fail', got %r", outcome)
+            return False
+        body = {"session_id": _scrub_text(str(session_id)), "outcome": outcome, "note": _scrub_text(note)}
+    except Exception as error:
+        log.warning("General Context could not build the outcome: %s", error)
+        return False
+    return _send_after_flush("/api/platform-collect/outcomes", body, "outcome")
+
+
+def log_event(session_id, event_type, properties=None, event_id=None, timestamp=None):
+    """Record something that happened in your systems (order.refunded, ticket.escalated). Pass a stable event_id so retries dedupe."""
+    try:
+        event = {"event_id": event_id or str(uuid.uuid4()), "event_type": _scrub_text(event_type),
+                 "timestamp": timestamp or _now(), "session_id": _scrub_text(str(session_id)),
+                 "properties": {key: _scrub_text(value) for key, value in (properties or {}).items()}}
+    except Exception as error:
+        log.warning("General Context could not build the event: %s", error)
+        return False
+    return _send_after_flush("/api/platform-collect/events", {"events": [event]}, "event")
+
+
+def _record(meta, response=None, error=None):
+    """Snapshot and enqueue one finished call. Never raises."""
+    try:
+        call = dict(meta["call"], response=_plain(response) if response is not None else None,
+                    ended_at=_now(), error=f"{type(error).__name__}: {error}" if error is not None else None)
+        _sender.put(call, meta["scrub"])
+    except Exception as failure:
+        log.warning("General Context could not record a model call: %s", failure)
+
+
+def _start(api, request, scrub=None):
+    return {"scrub": scrub or _config["scrub"], "call": {
+        "api": api, "conversation": _session.get(), "task": _task.get(),
+        "request": _plain(request), "started_at": _now()}}
+
+
+# ---- SDK patching --------------------------------------------------------------------------
+
+def _safe_start(api, request, scrub=None):
+    try:
+        return _start(api, request, scrub)
+    except Exception as error:
+        _warn("start", "General Context could not snapshot a model call; it runs unrecorded: %s", error)
+        return None
+
+
+def _recording(create, api, is_async, scrub=None):
+    """Wrap a `create` method so each call is recorded. The caller gets exactly what `create` returns."""
+    if is_async:
+        @functools.wraps(create)
+        async def wrapped(*args, **kwargs):
+            if _inside.get():
+                return await create(*args, **kwargs)
+            meta = _safe_start(api, kwargs, scrub)
+            if meta is None:
+                return await create(*args, **kwargs)
+            token = _inside.set(True)
+            try:
+                reply = await create(*args, **kwargs)
+            except Exception as error:
+                _record(meta, error=error)
+                raise
+            finally:
+                _inside.reset(token)
+            if kwargs.get("stream") is True:
+                return _AsyncStream(reply, meta)
+            _record(meta, reply)
+            return reply
+    else:
+        @functools.wraps(create)
+        def wrapped(*args, **kwargs):
+            if _inside.get():
+                return create(*args, **kwargs)
+            meta = _safe_start(api, kwargs, scrub)
+            if meta is None:
+                return create(*args, **kwargs)
+            token = _inside.set(True)
+            try:
+                reply = create(*args, **kwargs)
+            except Exception as error:
+                _record(meta, error=error)
+                raise
+            finally:
+                _inside.reset(token)
+            if kwargs.get("stream") is True:
+                return _SyncStream(reply, meta)
+            _record(meta, reply)
+            return reply
+    wrapped._generalcontext = True
+    return wrapped
+
+
+class _StreamBase:
+    """Passes chunks through unchanged and records the assembled reply once the stream ends."""
+
+    def __init__(self, inner, meta):
+        self._inner, self._meta, self._chunks, self._done = inner, meta, [], False
+
+    def _finish(self, error=None):
+        if not self._done:
+            self._done = True
+            _record(self._meta, None if error else _assemble(self._meta["call"]["api"], self._chunks), error)
+
+    def _keep(self, chunk):
+        try:
+            self._chunks.append(_plain(chunk))
+        except Exception:
+            pass
+        return chunk
+
+    def __getattr__(self, name):
+        return getattr(self._inner, name)
+
+
+class _SyncStream(_StreamBase):
+    def __iter__(self):
+        return self
+
+    def __next__(self):
+        if not hasattr(self, "_iterator"):
+            self._iterator = iter(self._inner)
+        try:
+            return self._keep(next(self._iterator))
+        except StopIteration:
+            self._finish()
+            raise
+        except Exception as error:
+            self._finish(error)
+            raise
+
+    def close(self):
+        try:
+            self._inner.close()
+        finally:
+            self._finish()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+
+class _AsyncStream(_StreamBase):
+    def __aiter__(self):
+        return self
+
+    async def __anext__(self):
+        if not hasattr(self, "_iterator"):
+            self._iterator = self._inner.__aiter__()
+        try:
+            return self._keep(await self._iterator.__anext__())
+        except StopAsyncIteration:
+            self._finish()
+            raise
+        except Exception as error:
+            self._finish(error)
+            raise
+
+    async def close(self):
+        try:
+            await self._inner.close()
+        finally:
+            self._finish()
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *exc):
+        await self.close()
+
+
+def _recording_stream_manager(stream, is_async):
+    """Wrap Anthropic `messages.stream(...)`: record the SDK's final message snapshot on exit."""
+
+    @functools.wraps(stream)
+    def wrapped(*args, **kwargs):
+        meta = _safe_start("anthropic", dict(kwargs, stream=True))
+        inner = stream(*args, **kwargs)
+        return inner if meta is None else _StreamManager(inner, meta)
+    wrapped._generalcontext = True
+    return wrapped
+
+
+class _StreamManager:
+    def __init__(self, inner, meta):
+        self._inner, self._meta, self._stream = inner, meta, None
+
+    def _finish(self, error):
+        try:
+            snapshot = self._stream.current_message_snapshot if self._stream is not None else None
+        except Exception:
+            snapshot = None
+        _record(self._meta, snapshot, error)
+
+    def __enter__(self):
+        self._stream = self._inner.__enter__()
+        return self._stream
+
+    def __exit__(self, kind, error, trace):
+        self._finish(error)
+        return self._inner.__exit__(kind, error, trace)
+
+    async def __aenter__(self):
+        self._stream = await self._inner.__aenter__()
+        return self._stream
+
+    async def __aexit__(self, kind, error, trace):
+        self._finish(error)
+        return await self._inner.__aexit__(kind, error, trace)
+
+
+def _assemble(api, chunks):
+    """Turn streamed chunks into the reply a non-streamed call would have returned."""
+    if api == "openai-chat":
+        return _assemble_chat(chunks)
+    if api == "anthropic":
+        return _assemble_anthropic(chunks)
+    finals = [c["response"] for c in chunks if isinstance(c, dict) and c.get("type") in
+              ("response.completed", "response.incomplete", "response.failed")]
+    return finals[-1] if finals else {"events": chunks}
+
+
+def _assemble_chat(chunks):
+    text, tools, model, usage, finish = [], {}, None, None, None
+    for chunk in chunks:
+        model = chunk.get("model") or model
+        usage = chunk.get("usage") or usage
+        for choice in chunk.get("choices") or []:
+            if choice.get("index", 0) != 0:
+                continue
+            delta = choice.get("delta") or {}
+            text.append(delta.get("content") or "")
+            for call in delta.get("tool_calls") or []:
+                slot = tools.setdefault(call.get("index", 0), {"id": None, "type": "function",
+                                                                "function": {"name": "", "arguments": ""}})
+                slot["id"] = call.get("id") or slot["id"]
+                function = call.get("function") or {}
+                slot["function"]["name"] += function.get("name") or ""
+                slot["function"]["arguments"] += function.get("arguments") or ""
+            finish = choice.get("finish_reason") or finish
+    message = {"role": "assistant", "content": "".join(text) or None}
+    if tools:
+        message["tool_calls"] = [tools[index] for index in sorted(tools)]
+    return {"model": model, "choices": [{"index": 0, "message": message, "finish_reason": finish}], "usage": usage}
+
+
+def _assemble_anthropic(events):
+    message, blocks = {}, {}
+    for event in events:
+        kind = event.get("type")
+        if kind == "message_start":
+            message = dict(event.get("message") or {})
+        elif kind == "content_block_start":
+            blocks[event["index"]] = dict(event.get("content_block") or {})
+        elif kind == "content_block_delta":
+            block, delta = blocks.setdefault(event["index"], {}), event.get("delta") or {}
+            for field, key in (("text", "text"), ("partial_json", "_json"), ("thinking", "thinking")):
+                if field in delta:
+                    block[key] = block.get(key, "") + delta[field]
+            if "signature" in delta:
+                block["signature"] = delta["signature"]
+        elif kind == "message_delta":
+            message.update(event.get("delta") or {})
+            message["usage"] = {**(message.get("usage") or {}), **(event.get("usage") or {})}
+    for block in blocks.values():
+        if "_json" in block:
+            raw = block.pop("_json")
+            try:
+                block["input"] = json.loads(raw) if raw else {}
+            except ValueError:
+                block["input"] = raw
+    message["content"] = [blocks[index] for index in sorted(blocks)]
+    return message
+
+
+# ---- Raw HTTP capture ----------------------------------------------------------------------
+
+def _patch_http():
+    try:
+        import httpx
+    except ImportError:
+        httpx = None
+    if httpx is not None and not getattr(httpx.Client.send, "_generalcontext", False):
+        sync_send, async_send = httpx.Client.send, httpx.AsyncClient.send
+
+        def send(self, request, *args, **kwargs):
+            meta = _http_start(request.url, lambda: request.content)
+            if meta is None:
+                return sync_send(self, request, *args, **kwargs)
+            return _http_finish(meta, lambda: sync_send(self, request, *args, **kwargs), kwargs.get("stream"),
+                                lambda r: r.text)
+
+        async def asend(self, request, *args, **kwargs):
+            meta = _http_start(request.url, lambda: request.content)
+            if meta is None:
+                return await async_send(self, request, *args, **kwargs)
+            try:
+                response = await async_send(self, request, *args, **kwargs)
+            except Exception as error:
+                _record(meta, error=error)
+                raise
+            return _http_finish(meta, lambda: response, kwargs.get("stream"), lambda r: r.text)
+
+        send._generalcontext = asend._generalcontext = True
+        httpx.Client.send, httpx.AsyncClient.send = send, asend
+    try:
+        import requests
+    except ImportError:
+        return
+    if not getattr(requests.Session.send, "_generalcontext", False):
+        requests_send = requests.Session.send
+
+        def rsend(self, request, **kwargs):
+            meta = _http_start(request.url, lambda: request.body)
+            if meta is None:
+                return requests_send(self, request, **kwargs)
+            return _http_finish(meta, lambda: requests_send(self, request, **kwargs), kwargs.get("stream"),
+                                lambda r: r.text)
+
+        rsend._generalcontext = True
+        requests.Session.send = rsend
+
+
+def _http_start(url, body):
+    """Meta for a raw chat completions POST, or None when it is not one to record."""
+    try:
+        url = str(url).split("?")[0]
+        if _inside.get() or not url.endswith("/chat/completions") or url.startswith(_base_url() + "/api/platform-collect"):
+            return None
+        raw = body()
+        return _start("openai-chat", json.loads(raw.decode() if isinstance(raw, bytes) else raw))
+    except Exception:
+        return None
+
+
+def _http_finish(meta, send, streamed, text):
+    try:
+        response = send()
+    except Exception as error:
+        _record(meta, error=error)
+        raise
+    if streamed:
+        return response  # The body is still unread; reading it here would change what the caller gets.
+    try:
+        body = text(response)
+        if body.lstrip().startswith("data:"):
+            chunks = [json.loads(line[5:]) for line in body.splitlines()
+                      if line.startswith("data:") and line[5:].strip() != "[DONE]"]
+            _record(meta, _assemble_chat(chunks))
+        else:
+            _record(meta, json.loads(body))
+    except Exception as error:
+        log.warning("General Context could not read a chat completions response: %s", error)
+    return response
+
+
+# ---- Redaction -----------------------------------------------------------------------------
+
+PATTERNS = [
+    ("email", re.compile(r"[A-Za-z0-9._%+-]{1,64}@[A-Za-z0-9-]{1,63}(?:\.[A-Za-z0-9-]{1,63}){0,8}\.[A-Za-z]{2,24}")),
+    ("card", re.compile(r"\b(?:\d[ -]?){13,16}\b")),
+    ("ssn", re.compile(r"\b\d{3}-\d{2}-\d{4}\b")),
+    ("phone", re.compile(r"(?<![\w])\+?1?[\s.-]?\(?\d{3}\)?[\s.-]?\d{3}[\s.-]?\d{4}(?![\w])")),
+]
+
+
+def _redactor(redact):
+    if callable(redact):
+        return redact
+    if not redact:
+        return None
+    # A secret salt, the same across your processes, keeps placeholders stable everywhere while
+    # making them unlinkable to the raw value for anyone without it.
+    salt = os.environ.get("GENERALCONTEXT_REDACT_SALT", "").encode()
+    if not salt:
+        log.warning("GENERALCONTEXT_REDACT_SALT is not set; placeholders will differ between processes")
+        salt = os.urandom(16)
+
+    def placeholder(kind, value):
+        # Hash the normalized value, so (612) 555-0177 and +1 612-555-0177 read as the same number.
+        digits = "".join(ch for ch in value if ch.isdigit())
+        normal = value.lower() if kind == "email" else digits[-10:] if kind == "phone" else digits
+        return f"<{kind}:{hmac.new(salt, normal.encode(), hashlib.sha256).hexdigest()[:6]}>"
+
+    def scrub(text):
+        for kind, pattern in PATTERNS:
+            text = pattern.sub(lambda match: placeholder(kind, match.group()), text)
+        return text
+    return scrub
+
+
+def _scrubbed(value, scrub):
+    if scrub is None:
+        return value
+    if isinstance(value, str):
+        return scrub(value)
+    if isinstance(value, dict):
+        return {key: _scrubbed(item, scrub) for key, item in value.items()}
+    if isinstance(value, list):
+        return [_scrubbed(item, scrub) for item in value]
+    return value
+
+
+def _plain(value, depth=0):
+    """SDK objects (pydantic models) as plain JSON. Request bodies may hold anything; keep what serializes."""
+    if depth > 40:
+        return None
+    if inspect.isclass(value):  # e.g. response_format=SomeModel
+        return f"{value.__module__}.{value.__qualname__}"
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json", exclude_none=True)
+    if isinstance(value, dict):
+        return {str(key): _plain(item, depth + 1) for key, item in value.items()
+                if not str(key).startswith(("extra_headers", "timeout"))}
+    if isinstance(value, (list, tuple)):
+        return [_plain(item, depth + 1) for item in value]
+    if isinstance(value, (str, int, float, bool)) or value is None:
+        return value
+    return str(value)

generalcontext-0.2.0.dist-info/METADATA

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: generalcontext
+Version: 0.2.0
+Summary: Record your agent's OpenAI and Anthropic calls for General Context review and testing.
+Project-URL: Homepage, https://generalcontextlabs.com/platform
+Project-URL: Documentation, https://generalcontextlabs.com/platform/docs/sdk
+Project-URL: Source, https://github.com/GeneralContext/sdk/tree/main/python
+Project-URL: Issues, https://github.com/GeneralContext/sdk/issues
+Author-email: General Context Labs <research@generalcontextlabs.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,anthropic,evaluation,llm,observability,openai,opentelemetry
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# generalcontext
+
+Record your agent's model calls for the General Context platform. No dependencies, and never
+in your agent's way: calls are sent from a background thread, and our failures are logged, not raised.
+
+```bash
+pip install generalcontext
+export GENERALCONTEXT_API_KEY=gck_...   # from your workspace's Connect page
+```
+
+```python
+import generalcontext
+generalcontext.initialize(app_name="support-agent")   # once per process, at startup
+
+# Optional: group every call in one conversation under your own id
+with generalcontext.session(conversation_id, user_id=customer_id, channel="chat"):
+    with generalcontext.task("triage"):
+        reply = client.chat.completions.create(...)   # any OpenAI or Anthropic client
+```
+
+`initialize()` records every OpenAI (`chat.completions`, `responses`) and Anthropic (`messages`)
+call in the process, sync and async, streamed or not, from clients created before or after it.
+SDK clients are always recorded. Raw `httpx` and `requests` POSTs to `/chat/completions`
+are recorded only with `instrument_http=True`. Call it in every process: queue workers and forked
+children do not inherit it.
+
+## Flush before exit
+
+On serverless, in jobs, and before `os._exit()`, send what is queued:
+
+```python
+generalcontext.flush()   # synchronous, waits up to 10s, never raises
+```
+
+## Outcomes and events
+
+```python
+generalcontext.report_outcome(conversation_id, "fail", note="customer reopened the ticket")   # or "success"
+generalcontext.log_event(conversation_id, "order.refunded", {"amount": 42.5}, event_id=f"refund:{refund.id}")
+generalcontext.log_event(conversation_id, "handoff.to_human", {"reason": "billing"})
+```
+
+Both need the conversation to exist on our side first, so they flush pending calls before
+sending. Both return `True` when accepted and never raise. Pass a stable `event_id` so a
+retried event is counted once. Properties are flat strings, numbers and booleans.
+
+## Redaction
+
+```python
+generalcontext.initialize(redact=True)   # emails, phones, card- and SSN-like numbers
+generalcontext.initialize(redact=fn)     # or your own: str -> str, applied to every string
+```
+
+Values become stable placeholders (`<phone:3f2a1c>`) before anything leaves your process. Set
+`GENERALCONTEXT_REDACT_SALT` to one secret in every process so placeholders match.
+
+## Configuration
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `api_key` | `GENERALCONTEXT_API_KEY` | Workspace key. Without it nothing is sent. |
+| `base_url` | `GENERALCONTEXT_BASE_URL`, else `https://generalcontextlabs.com` | Must be `https://` (plain `http://` only for localhost). |
+| `app_name` | `None` | Label for this app. |
+| `redact` | `False` | `True` for built-in PII redaction, or a `str -> str` function. Also applied to outcomes and events. |
+| `before_send` | `None` | `fn(call) -> dict or None`, runs on the sender thread before redaction. `None` or an exception drops the call. |
+| `instrument_http` | `False` | Also record raw `httpx`/`requests` POSTs to `/chat/completions`. |
+| `disable_batch` | `False` | Send each call on its own. |
+
+| Env var | Meaning |
+| --- | --- |
+| `GENERALCONTEXT_API_KEY` | Default `api_key`. |
+| `GENERALCONTEXT_BASE_URL` | Default `base_url`. |
+| `GENERALCONTEXT_REDACT_SALT` | Shared secret so redaction placeholders match across processes. |
+| `GENERALCONTEXT_DISABLED` | `1`, `true` or `yes` makes `initialize()` do nothing. |
+
+`HTTPS_PROXY` and `SSL_CERT_FILE` are honored via `urllib`. Redirects are never followed.
+Calls over 4 MB are dropped, and the in-memory queue is capped at 64 MB. A second `initialize()`
+is ignored. `wrap(client)` and `conversation(...)` from 0.1 still work.
+
+Tests: `cd python && python -m unittest test_sdk -v`.
+
+## License
+
+Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).

generalcontext-0.2.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+generalcontext/__init__.py,sha256=Jbo8umNRoqpy-DsAOI-RsBzMCHt789Km6maTYxSdtQY,30837
+generalcontext-0.2.0.dist-info/METADATA,sha256=jC8nIvVQtA69O3wyK8kZmSWOzH7vUfw5S9dK2Bz5-gY,4845
+generalcontext-0.2.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+generalcontext-0.2.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+generalcontext-0.2.0.dist-info/licenses/NOTICE,sha256=rlm5IZ6r_Swmm_FTUUzDLv9q8yyg7Z3rIiedmH4f8jE,168
+generalcontext-0.2.0.dist-info/RECORD,,

generalcontext-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

generalcontext-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

generalcontext-0.2.0.dist-info/licenses/NOTICE

@@ -0,0 +1,5 @@
+General Context SDK
+Copyright 2026 General Context Labs, Inc.
+
+This product includes software developed at General Context Labs, Inc.
+(https://generalcontextlabs.com).