glimind 0.2.0__py3-none-any.whl

glimind/__init__.py

@@ -0,0 +1,6 @@
+"""Glimind — live reliability oracle for AI agent tools (Python client)."""
+from ._shape import derive_shape, scrub_error
+from .client import SDK_VERSION, Glimind
+
+__all__ = ["Glimind", "SDK_VERSION", "derive_shape", "scrub_error"]
+Sentinel = Glimind  # back-compat alias

glimind/_shape.py

@@ -0,0 +1,54 @@
+"""Local, value-free shape derivation. Caller values NEVER survive — every leaf
+becomes a type tag; only dict keys (tool-schema field names) are kept. Mirrors the
+TypeScript SDK so shapes hash identically across languages."""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_TYPE_TAGS = {"<string>", "<number>", "<boolean>", "<null>", "<array>", "<object>", "<empty>"}
+
+
+def derive_shape(value: Any, depth: int = 0) -> Any:
+    if depth > 6:
+        return "<object>"
+    if value is None:
+        return "<null>"
+    # bool must be checked before int (bool is an int subclass in Python).
+    if isinstance(value, bool):
+        return "<boolean>"
+    if isinstance(value, (int, float)):
+        return "<number>"
+    if isinstance(value, str):
+        return "<string>"
+    if isinstance(value, (list, tuple)):
+        return [derive_shape(value[0], depth + 1)] if value else "<empty>"
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        for k in sorted(str(x) for x in value.keys()):
+            if len(k) > 64:
+                continue
+            out[k] = derive_shape(value[k], depth + 1)
+        return out
+    return "<object>"
+
+
+_SCRUBBERS = [
+    (re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}"), "<email>"),
+    (re.compile(r"\b(?:\d{1,3}\.){3}\d{1,3}\b"), "<ip>"),
+    (re.compile(r"\bBearer\s+[A-Za-z0-9._-]+", re.I), "Bearer <token>"),
+    (re.compile(r"\bsk-[A-Za-z0-9_-]{10,}\b"), "<token>"),
+    (re.compile(r"\b[A-Fa-f0-9]{32,}\b"), "<hex>"),
+    (re.compile(r"https?://[^\s\"']+"), "<url>"),
+    (re.compile(r"\"[^\"]{40,}\""), '"<str>"'),
+]
+
+
+def scrub_error(err: Any) -> str | None:
+    if err is None:
+        return None
+    s = f"{type(err).__name__}: {err}" if isinstance(err, BaseException) else str(err)
+    for rx, rep in _SCRUBBERS:
+        s = rx.sub(rep, s)
+    s = re.sub(r"\s+", " ", s).strip()
+    return s[:160] or None

glimind/client.py

@@ -0,0 +1,283 @@
+"""Glimind Python client — zero third-party dependencies (stdlib only).
+
+Ask if a tool works before calling it, and report your own outcomes
+(privacy-preserving) so the data gets better for everyone. Reporting is batched
+on a background daemon thread and flushed at exit, so it adds no latency to your
+tool calls.
+
+    from glimind import Glimind
+    s = Glimind(endpoint="https://glimind.com")
+    with s.wrap("acme/search", input={"q": "..."}, task="search"):
+        result = acme.search(q)         # outcome auto-reported (success/failure/latency)
+"""
+from __future__ import annotations
+
+import atexit
+import json
+import threading
+import time
+import urllib.parse
+import urllib.request
+from contextlib import contextmanager
+from typing import Any, Callable, Iterable
+
+from ._shape import derive_shape, scrub_error
+
+SDK_VERSION = "0.1.0"
+
+
+class Glimind:
+    def __init__(
+        self,
+        endpoint: str = "https://glimind.com",
+        api_key: str | None = None,
+        reporter_id: str | None = None,
+        region: str | None = None,
+        report: bool = True,
+        flush_interval: float = 5.0,
+        batch_size: int = 50,
+        timeout: float = 5.0,
+    ) -> None:
+        self.endpoint = endpoint.rstrip("/")
+        self.api_key = api_key
+        self.reporter_id = reporter_id
+        self.region = region
+        self._report = report
+        self._batch_size = batch_size
+        self._timeout = timeout
+        self._queue: list[dict] = []
+        self._lock = threading.Lock()
+        self._stop = threading.Event()
+        if report and flush_interval > 0:
+            self._thread = threading.Thread(target=self._loop, args=(flush_interval,), daemon=True)
+            self._thread.start()
+            atexit.register(self.close)
+
+    # --- query --------------------------------------------------------------
+    def check(self, tool_id: str) -> dict:
+        """Live health verdict for a tool (call before invoking it)."""
+        return self._get(f"/v1/health/{urllib.parse.quote(tool_id, safe='')}")
+
+    def score(self, tool_id: str) -> dict:
+        """Neutral reliability score + grade for a tool."""
+        return self._get(f"/v1/score/{urllib.parse.quote(tool_id, safe='')}")
+
+    def discover(self, query: str, limit: int | None = None) -> dict:
+        """Find live tools for a task described in plain language."""
+        q = urllib.parse.urlencode({"q": query, **({"limit": limit} if limit else {})})
+        return self._get(f"/v1/search?{q}")
+
+    # --- alerts -------------------------------------------------------------
+    def watch(self, tools=None, webhook=None, all_critical=None, min_severity=None) -> dict:
+        """Subscribe to reliability alerts. Pass webhook for push, or omit for a
+        pull token you poll with notifications(). Returns {id, token, channel}."""
+        if isinstance(tools, str):
+            tools = [tools]
+        payload = {
+            "url": webhook,
+            "tools": tools or [],
+            "allCritical": all_critical,
+            "minSeverity": min_severity,
+        }
+        return self._post("/v1/subscriptions", payload)
+
+    def notifications(self, token: str, limit: int | None = None) -> dict:
+        q = urllib.parse.urlencode({"token": token, **({"limit": limit} if limit else {})})
+        return self._get(f"/v1/notifications?{q}")
+
+    def poll_alerts(self, token: str, on_event, interval: float = 15.0):
+        """Block-polling loop: calls on_event(event) for each new alert. Returns a
+        threading.Event; set it to stop. Runs on a daemon thread."""
+        stop = threading.Event()
+
+        def loop():
+            while not stop.wait(0 if stop.is_set() else 0.01):
+                try:
+                    for e in self.notifications(token).get("events", []):
+                        on_event(e)
+                except Exception:  # noqa: BLE001
+                    pass
+                if stop.wait(interval):
+                    break
+
+        threading.Thread(target=loop, daemon=True).start()
+        return stop
+
+    def unwatch(self, token: str) -> dict:
+        q = urllib.parse.urlencode({"token": token})
+        req = urllib.request.Request(self.endpoint + f"/v1/subscriptions?{q}", headers=self._headers(), method="DELETE")
+        with urllib.request.urlopen(req, timeout=self._timeout) as r:  # noqa: S310
+            return json.loads(r.read().decode("utf-8"))
+
+    # --- report -------------------------------------------------------------
+    def report(
+        self,
+        tool_id: str,
+        success: bool,
+        input: Any = None,
+        error: Any = None,
+        latency_ms: int | None = None,
+        task: str | None = None,
+        routed: bool | None = None,
+        via_failover: bool | None = None,
+        attempts: int | None = None,
+    ) -> None:
+        if not self._report:
+            return
+        ev = {
+            "toolId": tool_id,
+            "shape": derive_shape(input) if input is not None else None,
+            "success": success,
+            "error": None if success else scrub_error(error),
+            "latencyMs": latency_ms,
+            "taskLabel": task,
+            "routed": routed,
+            "viaFailover": via_failover,
+            "attempts": attempts,
+            "ts": time.strftime("%Y-%m-%dT%H:%M:%S", time.gmtime()) + "Z",
+        }
+        with self._lock:
+            self._queue.append(ev)
+            n = len(self._queue)
+        if n >= self._batch_size:
+            self.flush()
+
+    @contextmanager
+    def wrap(self, tool_id: str, input: Any = None, task: str | None = None):
+        """Context manager: times the block and reports success/failure."""
+        start = time.monotonic()
+        try:
+            yield
+        except BaseException as e:  # noqa: BLE001
+            self.report(tool_id, False, input=input, error=e, latency_ms=int((time.monotonic() - start) * 1000), task=task)
+            raise
+        else:
+            self.report(tool_id, True, input=input, latency_ms=int((time.monotonic() - start) * 1000), task=task)
+
+    def prepare(self, tool_id: str, task: str | None = None) -> dict:
+        """Health + recipe + alternatives + call hints for a tool, in one call."""
+        path = f"/v1/prepare/{urllib.parse.quote(tool_id, safe='')}"
+        if task:
+            path += "?task=" + urllib.parse.quote(task, safe="")
+        return self._get(path)
+
+    def execute(
+        self,
+        tool_id: str,
+        call: Callable[[str], Any],
+        task: str | None = None,
+        input: Any = None,
+        allow_failover: bool = True,
+        max_retries: int | None = None,
+        max_failovers: int = 2,
+    ) -> Any:
+        """Reliability-aware execution: run call(tool_id) with learned retry and,
+        if it keeps failing, automatic failover to a healthy alternative tool.
+        Reports every attempt (privacy-clean), marked as execution-driven."""
+        prep: dict = {}
+        try:
+            prep = self.prepare(tool_id, task)
+        except Exception:  # noqa: BLE001
+            prep = {}
+        alts = [a for a in (prep.get("alternatives") or []) if a.get("toolId") and a.get("recommendation") != "avoid"]
+        if prep.get("recommendation") == "avoid":
+            ordered = [a["toolId"] for a in alts] + [tool_id]
+        else:
+            ordered = [tool_id] + ([a["toolId"] for a in alts] if allow_failover else [])
+        # de-dup preserving order, bound failover breadth
+        seen: set[str] = set()
+        deduped: list[str] = []
+        for t in ordered:
+            if t not in seen:
+                seen.add(t)
+                deduped.append(t)
+        deduped = deduped[: 1 + (max_failovers if allow_failover else 0)] or [tool_id]
+
+        hints = prep.get("callHints") or {}
+        retryable = (hints.get("retry") or {}).get("retryable") is not False
+        retries = max_retries if max_retries is not None else (2 if retryable else 0)
+
+        last_err: Exception | None = None
+        global_attempt = 0
+        for ci, chosen in enumerate(deduped):
+            via_failover = ci > 0
+            for attempt in range(retries + 1):
+                global_attempt += 1
+                start = time.monotonic()
+                try:
+                    out = call(chosen)
+                    self.report(chosen, True, input=input, latency_ms=int((time.monotonic() - start) * 1000),
+                                task=task, routed=True, via_failover=via_failover, attempts=global_attempt)
+                    return out
+                except Exception as e:  # noqa: BLE001
+                    last_err = e
+                    self.report(chosen, False, input=input, error=e, latency_ms=int((time.monotonic() - start) * 1000),
+                                task=task, routed=True, via_failover=via_failover, attempts=global_attempt)
+                    if attempt < retries:
+                        time.sleep(min(2.0, 0.15 * (2 ** attempt)))
+        if last_err:
+            raise last_err
+        raise RuntimeError("glimind.execute: no candidate tools")
+
+    def instrument(self, tool_id: str, task: str | None = None) -> Callable:
+        """Decorator form of wrap() for a function tool."""
+        def deco(fn: Callable) -> Callable:
+            def inner(*args, **kwargs):
+                with self.wrap(tool_id, input={"args": args, "kwargs": kwargs}, task=task):
+                    return fn(*args, **kwargs)
+            inner.__name__ = getattr(fn, "__name__", "tool")
+            return inner
+        return deco
+
+    # --- internals ----------------------------------------------------------
+    def _headers(self) -> dict[str, str]:
+        h = {"content-type": "application/json"}
+        if self.api_key:
+            h["authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def _get(self, path: str) -> dict:
+        req = urllib.request.Request(self.endpoint + path, headers=self._headers(), method="GET")
+        with urllib.request.urlopen(req, timeout=self._timeout) as r:  # noqa: S310
+            return json.loads(r.read().decode("utf-8"))
+
+    def _post(self, path: str, payload: dict) -> dict:
+        body = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(self.endpoint + path, data=body, headers=self._headers(), method="POST")
+        with urllib.request.urlopen(req, timeout=self._timeout) as r:  # noqa: S310
+            return json.loads(r.read().decode("utf-8"))
+
+    def _loop(self, interval: float) -> None:
+        while not self._stop.wait(interval):
+            try:
+                self.flush()
+            except Exception:  # noqa: BLE001
+                pass
+
+    def flush(self) -> None:
+        with self._lock:
+            if not self._queue:
+                return
+            batch = self._queue[: self._batch_size]
+            self._queue = self._queue[self._batch_size :]
+        events: Iterable[dict] = [
+            {**e, "region": self.region, "reporterId": self.reporter_id, "sdkVersion": SDK_VERSION}
+            for e in batch
+        ]
+        body = json.dumps({"events": list(events)}).encode("utf-8")
+        req = urllib.request.Request(self.endpoint + "/v1/ingest", data=body, headers=self._headers(), method="POST")
+        try:
+            urllib.request.urlopen(req, timeout=self._timeout).close()  # noqa: S310
+        except Exception:  # noqa: BLE001
+            # Best-effort: reliability telemetry must never destabilize the host app.
+            pass
+
+    def close(self) -> None:
+        self._stop.set()
+        try:
+            self.flush()
+        except Exception:  # noqa: BLE001
+            pass
+
+# Back-compat alias (formerly 'Sentinel').
+Sentinel = Glimind

glimind/langchain.py

@@ -0,0 +1,86 @@
+"""LangChain / LangGraph (Python) middleware.
+
+    from glimind import Glimind
+    from glimind.langchain import GlimindCallbackHandler
+    s = Glimind(endpoint="https://glimind.com")
+    agent.invoke(input, config={"callbacks": [GlimindCallbackHandler(s)]})
+
+Reports the outcome of every tool the agent runs — one line, no per-tool wrapping.
+Subclasses BaseCallbackHandler when available, else falls back to a plain object
+(duck-typed) so importing this module never hard-requires langchain.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any
+from uuid import UUID
+
+from .client import Glimind
+
+try:  # pragma: no cover - import shim
+    from langchain_core.callbacks import BaseCallbackHandler as _Base  # type: ignore
+except Exception:  # noqa: BLE001
+    try:
+        from langchain.callbacks.base import BaseCallbackHandler as _Base  # type: ignore
+    except Exception:  # noqa: BLE001
+        class _Base:  # minimal fallback
+            pass
+
+
+class GlimindCallbackHandler(_Base):  # type: ignore[misc]
+    def __init__(self, glimind: Glimind, server_id: str = "langchain", task: str | None = None) -> None:
+        super().__init__()
+        self._s = glimind
+        self._server_id = server_id
+        self._task = task
+        self._runs: dict[str, dict] = {}
+
+    def on_tool_start(self, serialized: dict, input_str: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        name = (serialized or {}).get("name") or kwargs.get("name") or "tool"
+        self._runs[str(run_id)] = {
+            "tool_id": f"{self._server_id}/{name}",
+            "input": input_str,
+            "start": time.monotonic(),
+        }
+
+    def on_tool_end(self, output: Any, *, run_id: UUID, **kwargs: Any) -> None:
+        r = self._runs.pop(str(run_id), None)
+        if not r:
+            return
+        self._s.report(r["tool_id"], True, input=r["input"],
+                       latency_ms=int((time.monotonic() - r["start"]) * 1000), task=self._task)
+
+    def on_tool_error(self, error: BaseException, *, run_id: UUID, **kwargs: Any) -> None:
+        r = self._runs.pop(str(run_id), None)
+        if not r:
+            return
+        self._s.report(r["tool_id"], False, input=r["input"], error=error,
+                       latency_ms=int((time.monotonic() - r["start"]) * 1000), task=self._task)
+
+def wrap_langchain_tool(glimind: Glimind, tool: Any, server_id: str = "langchain",
+                        task: str | None = None, max_retries: int | None = None) -> Any:
+    """Reliability-wrap a LangChain tool (in place). The callback handler only
+    OBSERVES; wrap the tool to actually retry transient failures via Glimind's
+    reliability-aware executor (learned backoff; failover off — schemas differ)."""
+    name = getattr(tool, "name", "tool")
+    tool_id = f"{server_id}/{name}"
+    for method in ("invoke", "run"):
+        orig = getattr(tool, method, None)
+        if not callable(orig):
+            continue
+
+        def make(bound):
+            def wrapped(input: Any, config: Any = None, **kw: Any):
+                call = (lambda _id: bound(input, config, **kw)) if config is not None else (lambda _id: bound(input, **kw))
+                return glimind.execute(tool_id, call, task=task, input=input,
+                                       allow_failover=False, max_retries=max_retries)
+            return wrapped
+
+        try:
+            setattr(tool, method, make(orig))
+        except Exception:  # noqa: BLE001
+            pass  # some tools have read-only attrs; skip silently
+    return tool
+
+
+SentinelCallbackHandler = GlimindCallbackHandler  # back-compat alias

glimind/openai_agents.py

@@ -0,0 +1,76 @@
+"""OpenAI Agents SDK (Python) middleware.
+
+    from glimind import Glimind
+    from glimind.openai_agents import instrument_agent
+    s = Glimind(endpoint="https://glimind.com")
+    agent = instrument_agent(s, agent)   # every function tool now auto-reports
+
+Duck-typed: wraps each tool's async `on_invoke_tool`; no hard dependency on the
+`agents` package. Reporting is fire-and-forget.
+"""
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Any
+
+from .client import Glimind
+
+
+def instrument_function_tool(glimind: Glimind, tool: Any, server_id: str = "openai",
+                             task: str | None = None, reliability: bool = False,
+                             max_retries: int = 2) -> Any:
+    if not hasattr(tool, "on_invoke_tool"):
+        return tool
+    name = getattr(tool, "name", "tool")
+    tool_id = f"{server_id}/{name}"
+    original = tool.on_invoke_tool
+
+    async def wrapped(ctx: Any, input_json: Any):
+        shape_input = None
+        try:
+            shape_input = json.loads(input_json) if isinstance(input_json, str) else input_json
+        except Exception:  # noqa: BLE001
+            shape_input = None
+
+        # Reliability mode: retry transient failures with backoff (non-blocking),
+        # reporting each attempt as execution-driven. Failover stays off here.
+        if reliability:
+            last_err: BaseException | None = None
+            for attempt in range(max_retries + 1):
+                start = time.monotonic()
+                try:
+                    res = await original(ctx, input_json)
+                    glimind.report(tool_id, True, input=shape_input,
+                                   latency_ms=int((time.monotonic() - start) * 1000), task=task,
+                                   routed=True, via_failover=False, attempts=attempt + 1)
+                    return res
+                except BaseException as e:  # noqa: BLE001
+                    last_err = e
+                    glimind.report(tool_id, False, input=None, error=e,
+                                   latency_ms=int((time.monotonic() - start) * 1000), task=task,
+                                   routed=True, via_failover=False, attempts=attempt + 1)
+                    if attempt < max_retries:
+                        await asyncio.sleep(min(2.0, 0.15 * (2 ** attempt)))
+            raise last_err  # type: ignore[misc]
+
+        start = time.monotonic()
+        try:
+            res = await original(ctx, input_json)
+            glimind.report(tool_id, True, input=shape_input, latency_ms=int((time.monotonic() - start) * 1000), task=task)
+            return res
+        except BaseException as e:  # noqa: BLE001
+            glimind.report(tool_id, False, input=None, error=e, latency_ms=int((time.monotonic() - start) * 1000), task=task)
+            raise
+
+    tool.on_invoke_tool = wrapped
+    return tool
+
+
+def instrument_agent(glimind: Glimind, agent: Any, server_id: str = "openai", task: str | None = None,
+                     reliability: bool = False, max_retries: int = 2) -> Any:
+    for t in (getattr(agent, "tools", None) or []):
+        instrument_function_tool(glimind, t, server_id=server_id, task=task,
+                                 reliability=reliability, max_retries=max_retries)
+    return agent

glimind-0.2.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.4
+Name: glimind
+Version: 0.2.0
+Summary: Live reliability oracle for AI agent tools — ask if a tool works before calling it, and report outcomes (privacy-preserving). Zero dependencies.
+License: MIT
+Keywords: ai-agents,langchain,mcp,observability,openai-agents,reliability
+Requires-Python: >=3.9
+Provides-Extra: langchain
+Requires-Dist: langchain-core; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# glimind (Python)
+
+Live reliability oracle for AI agent tools. Ask if a tool works before calling it,
+and report your own outcomes (privacy-preserving) so the data gets better for
+everyone. **Zero third-party dependencies** (stdlib only); reporting is batched on
+a background daemon thread and flushed at exit, so it adds no latency to your calls.
+
+```bash
+pip install glimind
+```
+
+```python
+from glimind import Glimind
+
+s = Glimind(endpoint="https://glimind.com", api_key="sk_live_...")  # api_key optional
+
+# 1) ask before acting
+h = s.check("acme/search")
+if h["verdict"] == "down":
+    ...  # pick a fallback
+
+# 2) wrap a call — success/failure/latency reported automatically (privacy-clean)
+with s.wrap("acme/search", input={"q": query}, task="search"):
+    result = acme.search(query)
+
+# or decorate a function tool
+@s.instrument("acme/search", task="search")
+def search(q): ...
+```
+
+## Framework middleware — one line
+
+**LangChain / LangGraph:**
+```python
+from glimind.langchain import GlimindCallbackHandler
+agent.invoke(input, config={"callbacks": [GlimindCallbackHandler(s)]})
+```
+
+**OpenAI Agents SDK:**
+```python
+from glimind.openai_agents import instrument_agent
+agent = instrument_agent(s, agent)   # every function tool now auto-reports
+```
+
+## Privacy
+
+This client **never sends your arguments, payloads, or tool outputs.** Before anything
+leaves your process it is reduced to a value-free *shape skeleton* (every leaf value
+becomes a type tag), errors are scrubbed, and only: tool id, input shape, success/failure,
+normalized error, latency, coarse region are transmitted. The derivation is identical to
+the TypeScript SDK, so shapes hash consistently across languages.
+
+MIT licensed.

glimind-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+glimind/__init__.py,sha256=-JKf3TvxahytfD7kyNE-FO5viYQ-BVJGCX4EPfyQYQ0,274
+glimind/_shape.py,sha256=ee0-P67lAv2FCN-2XKm1GQsPF9wz43CetBoXpaRJ4L4,1913
+glimind/client.py,sha256=lgUFIKQzO47x-o4t2nAejB9e2XiS3_G1NyKB7BaePtc,11638
+glimind/langchain.py,sha256=thULD-El64XttVI6g2Sr2TNvVpbbBdwKUrekOzYG3kw,3608
+glimind/openai_agents.py,sha256=wVWZpyVlM5FcXhABv32NRv4DKxZ6HcvAD1mvY2t3TEo,3299
+glimind-0.2.0.dist-info/METADATA,sha256=bQPRz855Z4oLZ6yD9D6Be_zkxAX7Iyh1SwR02wvkE5g,2143
+glimind-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+glimind-0.2.0.dist-info/RECORD,,

glimind-0.2.0.dist-info/WHEEL

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