cognocient 0.1.0__tar.gz

cognocient-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.pytest_cache/
+build/
+dist/
+.venv/

cognocient-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cognocient
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cognocient-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: cognocient
+Version: 0.1.0
+Summary: Drop-in async-reporting wrapper for the OpenAI and Anthropic Python SDKs — live cost attribution without changing your base_url.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.25; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: anthropic>=0.25; extra == 'dev'
+Requires-Dist: openai>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# cognocient
+
+A drop-in wrapper around the OpenAI and Anthropic Python SDKs that reports
+usage to Cognocient asynchronously, so you get live cost attribution
+without changing your `base_url` or routing traffic through a proxy.
+
+```bash
+pip install cognocient[openai]      # or cognocient[anthropic], or both
+```
+
+```python
+# Before
+from openai import OpenAI
+client = OpenAI(api_key="sk-...")
+
+# After
+from cognocient import CognocientOpenAI as OpenAI
+client = OpenAI(
+    api_key="sk-...",              # your own real OpenAI key, used exactly as before
+    cognocient_key="sk-cog-...",   # the same proxy key you'd use with the Cognocient proxy
+)
+
+client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "hello"}],
+    cognocient_feature="support-bot",   # optional attribution — same field names the proxy accepts as X-Cost-* headers
+)
+```
+
+Every method the real SDK exposes still works unchanged. This wrapper only
+intercepts `chat.completions.create()` (`messages.create()` for Anthropic)
+to time the call and report its usage after the fact; everything else is
+forwarded to the real client untouched.
+
+## This is one of three ways to see your Cognocient dashboard
+
+| | Live attribution | Pre-call enforcement (block/degrade) | Code change |
+|---|---|---|---|
+| **Proxy** (`base_url` swap) | Yes | Yes | One line |
+| **This wrapper** | Yes | No — see below | Swap the import, add a key |
+| **CSV/OTel import** | No (historical only) | No | None |
+
+## Security — read this before you decide
+
+**This wrapper is not more secure than the proxy. It is a different
+tradeoff, not a strictly better one.**
+
+With the proxy, your real provider API key lives server-side, under
+Cognocient's control, in one place. With this wrapper, your real provider
+key stays in your own application process, exactly as it does today
+without Cognocient at all — the wrapper calls the provider directly,
+using your key, inside your runtime. Some security teams prefer that
+(no third-party network hop in the request path); others are less
+comfortable with third-party code executing inside their process with
+key access. Both are reasonable positions. We're not going to tell you
+this "removes a security roadblock" — it trades one shape of exposure
+for a different one.
+
+What this wrapper honestly gives you over the proxy:
+- **Zero added request latency.** Reporting happens after your real
+  call already returned, on a background thread, off the critical path.
+- **Zero risk of a Cognocient outage affecting your production call.**
+  If Cognocient's ingestion API is down or unreachable, your call to
+  OpenAI/Anthropic still completes normally — see "Reliability" below.
+
+What you give up versus the proxy: pre-call enforcement. Because
+Cognocient only hears about a call after it already happened, budgets
+configured in Cognocient cannot block or degrade a call made through
+this wrapper before it fires. The dashboard will say so explicitly for
+any account using this path.
+
+## Reliability
+
+Reporting is fire-and-forget on a background thread with a bounded local
+queue, flushed every few seconds or every 50 calls, whichever comes
+first. If the ingestion API is slow, down, or unreachable:
+
+- Your real provider call is completely unaffected — it already happened
+  before reporting was attempted.
+- No exception is ever raised into your code from a reporting failure.
+- No retry loop that could pile up work in your process — a failed batch
+  is dropped and logged locally at `DEBUG` level via the `cognocient`
+  logger, not retried.
+
+See `tests/test_reporter_failure_isolation.py` for a test that simulates
+an unreachable ingestion endpoint and asserts the real call still
+completes normally.
+
+## Known limitation: streaming isn't reported yet
+
+`stream=True` calls are passed through to the real SDK completely
+unmodified — your application behaves identically — but are **not**
+currently reported to Cognocient. Usage totals aren't available until a
+stream completes, and reliably capturing them requires wrapping the
+stream iterator itself, which this version doesn't do. If most of your
+traffic streams, this wrapper will under-report your usage today. Use
+the proxy or the CSV/OTel importer if that matters for your evaluation.
+
+## Attribution fields
+
+Same field names the proxy accepts as `X-Cost-*` headers, passed as
+keyword arguments instead:
+
+| Wrapper kwarg | Proxy header |
+|---|---|
+| `cognocient_feature` | `X-Cost-Feature` |
+| `cognocient_department` | `X-Cost-Department` |
+| `cognocient_user` | `X-Cost-User` |
+| `cognocient_session` | `X-Cost-Session` |
+| `cognocient_tier` | `X-Cost-Tier` |
+| `cognocient_project` | `X-Cost-Project` |
+| `cognocient_gl_account` | `X-Cost-GL-Account` |
+| `cognocient_workload` | `X-Cost-Workload` |
+| `cognocient_outcome` | `X-Cost-Outcome` |
+| `cognocient_run_id` | `X-Cost-Run-ID` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+python benchmark/benchmark_wrapper_overhead.py
+```

cognocient-0.1.0/README.md

@@ -0,0 +1,123 @@
+# cognocient
+
+A drop-in wrapper around the OpenAI and Anthropic Python SDKs that reports
+usage to Cognocient asynchronously, so you get live cost attribution
+without changing your `base_url` or routing traffic through a proxy.
+
+```bash
+pip install cognocient[openai]      # or cognocient[anthropic], or both
+```
+
+```python
+# Before
+from openai import OpenAI
+client = OpenAI(api_key="sk-...")
+
+# After
+from cognocient import CognocientOpenAI as OpenAI
+client = OpenAI(
+    api_key="sk-...",              # your own real OpenAI key, used exactly as before
+    cognocient_key="sk-cog-...",   # the same proxy key you'd use with the Cognocient proxy
+)
+
+client.chat.completions.create(
+    model="gpt-4o",
+    messages=[{"role": "user", "content": "hello"}],
+    cognocient_feature="support-bot",   # optional attribution — same field names the proxy accepts as X-Cost-* headers
+)
+```
+
+Every method the real SDK exposes still works unchanged. This wrapper only
+intercepts `chat.completions.create()` (`messages.create()` for Anthropic)
+to time the call and report its usage after the fact; everything else is
+forwarded to the real client untouched.
+
+## This is one of three ways to see your Cognocient dashboard
+
+| | Live attribution | Pre-call enforcement (block/degrade) | Code change |
+|---|---|---|---|
+| **Proxy** (`base_url` swap) | Yes | Yes | One line |
+| **This wrapper** | Yes | No — see below | Swap the import, add a key |
+| **CSV/OTel import** | No (historical only) | No | None |
+
+## Security — read this before you decide
+
+**This wrapper is not more secure than the proxy. It is a different
+tradeoff, not a strictly better one.**
+
+With the proxy, your real provider API key lives server-side, under
+Cognocient's control, in one place. With this wrapper, your real provider
+key stays in your own application process, exactly as it does today
+without Cognocient at all — the wrapper calls the provider directly,
+using your key, inside your runtime. Some security teams prefer that
+(no third-party network hop in the request path); others are less
+comfortable with third-party code executing inside their process with
+key access. Both are reasonable positions. We're not going to tell you
+this "removes a security roadblock" — it trades one shape of exposure
+for a different one.
+
+What this wrapper honestly gives you over the proxy:
+- **Zero added request latency.** Reporting happens after your real
+  call already returned, on a background thread, off the critical path.
+- **Zero risk of a Cognocient outage affecting your production call.**
+  If Cognocient's ingestion API is down or unreachable, your call to
+  OpenAI/Anthropic still completes normally — see "Reliability" below.
+
+What you give up versus the proxy: pre-call enforcement. Because
+Cognocient only hears about a call after it already happened, budgets
+configured in Cognocient cannot block or degrade a call made through
+this wrapper before it fires. The dashboard will say so explicitly for
+any account using this path.
+
+## Reliability
+
+Reporting is fire-and-forget on a background thread with a bounded local
+queue, flushed every few seconds or every 50 calls, whichever comes
+first. If the ingestion API is slow, down, or unreachable:
+
+- Your real provider call is completely unaffected — it already happened
+  before reporting was attempted.
+- No exception is ever raised into your code from a reporting failure.
+- No retry loop that could pile up work in your process — a failed batch
+  is dropped and logged locally at `DEBUG` level via the `cognocient`
+  logger, not retried.
+
+See `tests/test_reporter_failure_isolation.py` for a test that simulates
+an unreachable ingestion endpoint and asserts the real call still
+completes normally.
+
+## Known limitation: streaming isn't reported yet
+
+`stream=True` calls are passed through to the real SDK completely
+unmodified — your application behaves identically — but are **not**
+currently reported to Cognocient. Usage totals aren't available until a
+stream completes, and reliably capturing them requires wrapping the
+stream iterator itself, which this version doesn't do. If most of your
+traffic streams, this wrapper will under-report your usage today. Use
+the proxy or the CSV/OTel importer if that matters for your evaluation.
+
+## Attribution fields
+
+Same field names the proxy accepts as `X-Cost-*` headers, passed as
+keyword arguments instead:
+
+| Wrapper kwarg | Proxy header |
+|---|---|
+| `cognocient_feature` | `X-Cost-Feature` |
+| `cognocient_department` | `X-Cost-Department` |
+| `cognocient_user` | `X-Cost-User` |
+| `cognocient_session` | `X-Cost-Session` |
+| `cognocient_tier` | `X-Cost-Tier` |
+| `cognocient_project` | `X-Cost-Project` |
+| `cognocient_gl_account` | `X-Cost-GL-Account` |
+| `cognocient_workload` | `X-Cost-Workload` |
+| `cognocient_outcome` | `X-Cost-Outcome` |
+| `cognocient_run_id` | `X-Cost-Run-ID` |
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+python benchmark/benchmark_wrapper_overhead.py
+```

cognocient-0.1.0/benchmark/benchmark_wrapper_overhead.py

@@ -0,0 +1,114 @@
+"""
+Real, measured latency benchmark for the cognocient Python wrapper's
+call-path overhead.
+
+Methodology: compares (a) a direct call through the real openai.OpenAI
+client against (b) the identical call through CognocientOpenAI, both
+hitting the SAME in-process httpx.MockTransport (so provider network
+variance is excluded from both legs and cannot advantage either side).
+This isolates exactly what the wrapper's own interception code — timing,
+tag stripping, and queuing the report — costs on the customer's request
+path. It does NOT include reporting delivery time, because reporting
+runs on a background thread the request path never waits on; that's the
+architectural claim this benchmark exists to check, not assume.
+
+What's faked and why (disclosed here, not hidden):
+  - No real network call to OpenAI or to Cognocient's ingestion API —
+    both would introduce variance neither leg of this comparison is
+    trying to measure. Real network latency to either service is NOT
+    part of these numbers; only the wrapper's own added CPU work on the
+    request path is.
+  - The reporting queue is left completely unconsumed during the timed
+    loop (the background thread's flush interval is longer than the
+    whole benchmark run), so a measured cost that includes
+    queue.put_nowait() reflects the actual per-call cost, not a case
+    where a concurrently-draining queue happened to be cheap.
+
+Run: python benchmark/benchmark_wrapper_overhead.py
+"""
+
+import statistics
+import time
+
+import httpx
+import openai
+
+from cognocient import CognocientOpenAI
+
+ITERATIONS = 2000
+WARMUP = 200
+
+_CHAT_COMPLETION_JSON = {
+    "id": "chatcmpl-bench",
+    "object": "chat.completion",
+    "created": 1700000000,
+    "model": "gpt-4o-mini",
+    "choices": [{"index": 0, "message": {"role": "assistant", "content": "ok"}, "finish_reason": "stop"}],
+    "usage": {"prompt_tokens": 10, "completion_tokens": 2, "total_tokens": 12},
+}
+
+
+def _mock_transport():
+    def handler(request):
+        return httpx.Response(200, json=_CHAT_COMPLETION_JSON)
+    return httpx.MockTransport(handler)
+
+
+def _time_calls(create_fn, iterations):
+    samples = []
+    for _ in range(iterations):
+        start = time.perf_counter()
+        create_fn()
+        samples.append((time.perf_counter() - start) * 1000)  # ms
+    return samples
+
+
+def _pct(samples, p):
+    return statistics.quantiles(samples, n=100)[p - 1]
+
+
+def main():
+    real_client = openai.OpenAI(api_key="sk-bench-fake", http_client=httpx.Client(transport=_mock_transport()))
+    wrapped_client = CognocientOpenAI(
+        api_key="sk-bench-fake",
+        http_client=httpx.Client(transport=_mock_transport()),
+        cognocient_key="sk-cog-bench",
+        # Deliberately unreachable (nothing listens on loopback port 1) —
+        # if a future regression accidentally made the request path wait
+        # on delivery, that would show up here as a multi-second outlier,
+        # not a subtle few-ms difference easy to miss.
+        cognocient_ingest_url="http://127.0.0.1:1/api/ingest/wrapper",
+    )
+
+    def raw_call():
+        real_client.chat.completions.create(model="gpt-4o-mini", messages=[{"role": "user", "content": "hi"}])
+
+    def wrapped_call():
+        wrapped_client.chat.completions.create(
+            model="gpt-4o-mini",
+            messages=[{"role": "user", "content": "hi"}],
+            cognocient_feature="benchmark",
+        )
+
+    _time_calls(raw_call, WARMUP)
+    _time_calls(wrapped_call, WARMUP)
+
+    raw_samples = _time_calls(raw_call, ITERATIONS)
+    wrapped_samples = _time_calls(wrapped_call, ITERATIONS)
+
+    print(f"Iterations per leg: {ITERATIONS}\n")
+    print(f"{'':20} {'p50 (ms)':>10} {'p95 (ms)':>10} {'p99 (ms)':>10} {'mean (ms)':>10}")
+    print(f"{'Raw SDK call':20} {_pct(raw_samples, 50):>10.4f} {_pct(raw_samples, 95):>10.4f} "
+          f"{_pct(raw_samples, 99):>10.4f} {statistics.mean(raw_samples):>10.4f}")
+    print(f"{'Wrapped call':20} {_pct(wrapped_samples, 50):>10.4f} {_pct(wrapped_samples, 95):>10.4f} "
+          f"{_pct(wrapped_samples, 99):>10.4f} {statistics.mean(wrapped_samples):>10.4f}")
+
+    added_p50 = _pct(wrapped_samples, 50) - _pct(raw_samples, 50)
+    added_mean = statistics.mean(wrapped_samples) - statistics.mean(raw_samples)
+    print(f"\nAdded overhead vs raw SDK — p50: {added_p50:.4f} ms, mean: {added_mean:.4f} ms")
+    print("\n(Real network latency to OpenAI/Anthropic and to Cognocient's ingestion API")
+    print(" is NOT included above — see this script's module docstring for why.)")
+
+
+if __name__ == "__main__":
+    main()

cognocient-0.1.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cognocient"
+version = "0.1.0"
+description = "Drop-in async-reporting wrapper for the OpenAI and Anthropic Python SDKs — live cost attribution without changing your base_url."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+anthropic = ["anthropic>=0.25"]
+dev = ["pytest>=7.0", "openai>=1.0", "anthropic>=0.25"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/cognocient"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

cognocient-0.1.0/src/cognocient/__init__.py

@@ -0,0 +1,6 @@
+from ._reporter import CallReport, Reporter, DEFAULT_INGEST_URL
+from .openai_wrapper import CognocientOpenAI
+from .anthropic_wrapper import CognocientAnthropic
+
+__all__ = ["CognocientOpenAI", "CognocientAnthropic", "CallReport", "Reporter", "DEFAULT_INGEST_URL"]
+__version__ = "0.1.0"

cognocient-0.1.0/src/cognocient/_reporter.py

@@ -0,0 +1,142 @@
+"""
+Async batching reporter — fires call metadata to Cognocient's ingestion
+API without ever blocking or delaying the customer's real provider call,
+and without ever raising back into their code.
+
+Runs its own background daemon thread with a plain stdlib queue.Queue,
+independent of whether the customer's application uses asyncio at all.
+Most of the value of this wrapper is for the plain synchronous
+openai.OpenAI() / anthropic.Anthropic() clients shown in the README,
+which have no event loop to hang an asyncio task off of — a thread-based
+worker is the one design that reports reliably regardless of whether the
+calling application is sync or async.
+"""
+
+import atexit
+import logging
+import queue
+import threading
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+import httpx
+
+logger = logging.getLogger("cognocient")
+
+DEFAULT_INGEST_URL = "https://api.cognocient.com/api/ingest/wrapper"
+FLUSH_INTERVAL_SECONDS = 5.0
+FLUSH_MAX_BATCH = 50
+QUEUE_MAX_SIZE = 500
+
+
+@dataclass
+class CallReport:
+    model: str
+    provider: str
+    prompt_tokens: int
+    completion_tokens: int
+    latency_ms: int
+    status_code: int = 200
+    cost_usd: Optional[float] = None
+    tag_feature: Optional[str] = None
+    tag_department: Optional[str] = None
+    tag_user: Optional[str] = None
+    tag_session: Optional[str] = None
+    tag_tier: Optional[str] = None
+    tag_project: Optional[str] = None
+    tag_gl_account: Optional[str] = None
+    tag_workload: Optional[str] = None
+    tag_outcome: Optional[str] = None
+    run_id: Optional[str] = None
+
+
+class Reporter:
+    """
+    One instance per client. Every failure mode (network error, ingestion
+    API unreachable, local queue full) is caught and logged locally at
+    DEBUG level — never raised back into the caller. This is the actual
+    reliability guarantee of the wrapper; it has to hold here, not just be
+    claimed in the docs. See tests/test_reporter_failure_isolation.py.
+    """
+
+    def __init__(
+        self,
+        cognocient_key: str,
+        ingest_url: str = DEFAULT_INGEST_URL,
+        flush_interval: float = FLUSH_INTERVAL_SECONDS,
+        flush_max_batch: int = FLUSH_MAX_BATCH,
+        queue_max_size: int = QUEUE_MAX_SIZE,
+        http_timeout: float = 5.0,
+    ):
+        self._cognocient_key = cognocient_key
+        self._ingest_url = ingest_url
+        self._flush_interval = flush_interval
+        self._flush_max_batch = flush_max_batch
+        self._queue: "queue.Queue[CallReport]" = queue.Queue(maxsize=queue_max_size)
+        self._client = httpx.Client(timeout=http_timeout)
+        self._dropped_count = 0
+        self._wake = threading.Event()
+        self._stop = False
+        self._thread = threading.Thread(target=self._run, name="cognocient-reporter", daemon=True)
+        self._thread.start()
+        atexit.register(self._shutdown)
+
+    def report(self, call: CallReport) -> None:
+        """Non-blocking, never raises. Call this right after the real provider call returns."""
+        try:
+            self._queue.put_nowait(call)
+            if self._queue.qsize() >= self._flush_max_batch:
+                self._wake.set()
+        except queue.Full:
+            self._dropped_count += 1
+            logger.debug(
+                "cognocient: reporting queue full, dropped a report (%d dropped total)",
+                self._dropped_count,
+            )
+        except Exception:
+            logger.debug("cognocient: failed to queue a report", exc_info=True)
+
+    def flush(self) -> None:
+        """Force an immediate flush — e.g. before a short-lived script exits."""
+        try:
+            self._flush()
+        except Exception:
+            logger.debug("cognocient: manual flush failed", exc_info=True)
+
+    def _run(self) -> None:
+        while not self._stop:
+            self._wake.wait(timeout=self._flush_interval)
+            self._wake.clear()
+            self._flush()
+        self._flush()  # final drain on shutdown
+
+    def _flush(self) -> None:
+        batch = []
+        while len(batch) < self._flush_max_batch:
+            try:
+                batch.append(self._queue.get_nowait())
+            except queue.Empty:
+                break
+        if not batch:
+            return
+        try:
+            self._client.post(
+                self._ingest_url,
+                json={"reports": [asdict(c) for c in batch]},
+                headers={"Authorization": f"Bearer {self._cognocient_key}"},
+            )
+        except Exception:
+            # Network error, timeout, Cognocient down — never propagate.
+            # The batch is simply dropped; retrying would risk piling up
+            # unbounded background work in the customer's process for
+            # something that is not their application's job to guarantee.
+            logger.debug("cognocient: failed to report %d call(s)", len(batch), exc_info=True)
+
+    def _shutdown(self) -> None:
+        try:
+            self._stop = True
+            self._wake.set()
+            self._thread.join(timeout=2.0)
+            self._client.close()
+        except Exception:
+            logger.debug("cognocient: error during reporter shutdown", exc_info=True)

cognocient-0.1.0/src/cognocient/_tags.py

@@ -0,0 +1,32 @@
+"""
+Attribution kwargs, matching the exact tag names the Cognocient proxy
+already accepts as X-Cost-* headers (backend/app/proxy.py tag_header_map)
+so a customer moving between the wrapper and the proxy uses the same
+tagging model, not two different ones to learn.
+"""
+
+TAG_KWARGS = (
+    "cognocient_feature",
+    "cognocient_department",
+    "cognocient_user",
+    "cognocient_session",
+    "cognocient_tier",
+    "cognocient_project",
+    "cognocient_gl_account",
+    "cognocient_workload",
+    "cognocient_outcome",
+    "cognocient_run_id",
+)
+
+
+def pop_tags(kwargs: dict) -> dict:
+    """Strips cognocient_* kwargs out of a call's kwargs and returns them
+    mapped to CallReport field names, so the real SDK call underneath never
+    sees (and never rejects) an argument it doesn't recognize."""
+    tags = {}
+    for key in TAG_KWARGS:
+        if key in kwargs:
+            value = kwargs.pop(key)
+            name = key[len("cognocient_"):]
+            tags["run_id" if name == "run_id" else f"tag_{name}"] = value
+    return tags

cognocient-0.1.0/src/cognocient/anthropic_wrapper.py

@@ -0,0 +1,89 @@
+"""
+Drop-in wrapper around anthropic.Anthropic that reports every completed
+messages.create() call to Cognocient asynchronously, without ever
+blocking or delaying the real call to Anthropic, and without ever raising
+a reporting failure back into the caller.
+
+See openai_wrapper.py's module docstring for the security framing (same
+tradeoffs apply here — this is not "more secure" than the proxy) and the
+streaming limitation (also identical: non-streaming only in this version).
+"""
+
+import time
+from typing import Any
+
+from ._reporter import DEFAULT_INGEST_URL, CallReport, Reporter
+from ._tags import pop_tags
+
+
+class _ReportingMessages:
+    def __init__(self, real_messages: Any, reporter: Reporter, provider: str):
+        self._real = real_messages
+        self._reporter = reporter
+        self._provider = provider
+
+    def create(self, *args, **kwargs):
+        tags = pop_tags(kwargs)
+        is_streaming = bool(kwargs.get("stream"))
+
+        start = time.monotonic()
+        response = self._real.create(*args, **kwargs)
+        latency_ms = int((time.monotonic() - start) * 1000)
+
+        if is_streaming:
+            return response  # not reported in this version — see module docstring
+
+        try:
+            usage = getattr(response, "usage", None)
+            model = getattr(response, "model", None) or kwargs.get("model", "unknown")
+            # Anthropic's usage field names differ from OpenAI's — input/output, not prompt/completion.
+            prompt_tokens = getattr(usage, "input_tokens", 0) if usage else 0
+            completion_tokens = getattr(usage, "output_tokens", 0) if usage else 0
+            self._reporter.report(CallReport(
+                model=model,
+                provider=self._provider,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                latency_ms=latency_ms,
+                status_code=200,
+                **tags,
+            ))
+        except Exception:
+            pass
+
+        return response
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+
+class CognocientAnthropic:
+    """
+    Drop-in replacement import for anthropic.Anthropic:
+
+        from cognocient import CognocientAnthropic as Anthropic
+        client = Anthropic(
+            api_key="sk-ant-...",         # your own real Anthropic key
+            cognocient_key="sk-cog-...",  # your Cognocient proxy key, reused here
+        )
+        client.messages.create(
+            model="claude-sonnet-4-6", max_tokens=1024, messages=[...],
+            cognocient_feature="support-bot",
+        )
+    """
+
+    def __init__(self, *args, cognocient_key: str, cognocient_ingest_url: str = DEFAULT_INGEST_URL, **kwargs):
+        try:
+            import anthropic
+        except ImportError as e:
+            raise ImportError(
+                "cognocient.CognocientAnthropic requires the 'anthropic' package. "
+                "Install it with: pip install cognocient[anthropic]"
+            ) from e
+
+        self._real = anthropic.Anthropic(*args, **kwargs)
+        self._reporter = Reporter(cognocient_key, ingest_url=cognocient_ingest_url)
+        self.messages = _ReportingMessages(self._real.messages, self._reporter, "anthropic")
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)

cognocient-0.1.0/src/cognocient/openai_wrapper.py

@@ -0,0 +1,124 @@
+"""
+Drop-in wrapper around openai.OpenAI that reports every completed
+chat.completions.create() call to Cognocient asynchronously, without ever
+blocking or delaying the real call to OpenAI, and without ever raising a
+reporting failure back into the caller.
+
+SECURITY NOTE (read before writing any customer-facing copy referencing
+this file): this wrapper runs INSIDE your application process and holds
+your real OpenAI API key to make the call directly. That is a DIFFERENT
+security exposure than the Cognocient proxy (where the key lives
+server-side, under Cognocient's control, in one place) — not a strictly
+lesser one. This wrapper is NOT "more secure" than the proxy. Its honest,
+defensible benefits are zero added request latency and zero risk of a
+Cognocient outage affecting your production call. See ../README.md.
+
+LIMITATION: usage reporting only covers non-streaming calls in this
+version. Streaming calls (stream=True) are passed through to the real SDK
+completely unmodified — your application behaves identically — but are
+not currently reported to Cognocient, since usage totals aren't available
+until a stream completes, and reliably capturing them requires wrapping
+the stream iterator itself, which this version doesn't do. If most of
+your traffic streams, this wrapper will under-report your usage today.
+"""
+
+import time
+from typing import Any
+
+from ._reporter import DEFAULT_INGEST_URL, CallReport, Reporter
+from ._tags import pop_tags
+
+
+class _ReportingCompletions:
+    """Wraps client.chat.completions — every attribute except create()
+    is forwarded untouched to the real SDK object."""
+
+    def __init__(self, real_completions: Any, reporter: Reporter, provider: str):
+        self._real = real_completions
+        self._reporter = reporter
+        self._provider = provider
+
+    def create(self, *args, **kwargs):
+        tags = pop_tags(kwargs)
+        is_streaming = bool(kwargs.get("stream"))
+
+        start = time.monotonic()
+        # The real call always happens first, and its result/exception is
+        # returned to the caller exactly as the real SDK would — nothing
+        # about reporting can change this line's outcome.
+        response = self._real.create(*args, **kwargs)
+        latency_ms = int((time.monotonic() - start) * 1000)
+
+        if is_streaming:
+            return response  # not reported in this version — see module docstring
+
+        try:
+            usage = getattr(response, "usage", None)
+            model = getattr(response, "model", None) or kwargs.get("model", "unknown")
+            prompt_tokens = getattr(usage, "prompt_tokens", 0) if usage else 0
+            completion_tokens = getattr(usage, "completion_tokens", 0) if usage else 0
+            self._reporter.report(CallReport(
+                model=model,
+                provider=self._provider,
+                prompt_tokens=prompt_tokens,
+                completion_tokens=completion_tokens,
+                latency_ms=latency_ms,
+                status_code=200,
+                **tags,
+            ))
+        except Exception:
+            # A bug in this wrapper's own bookkeeping must never surface
+            # to the caller — the real response above has already
+            # returned successfully by this point.
+            pass
+
+        return response
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+
+class _ReportingChat:
+    def __init__(self, real_chat: Any, reporter: Reporter, provider: str):
+        self._real = real_chat
+        self.completions = _ReportingCompletions(real_chat.completions, reporter, provider)
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)
+
+
+class CognocientOpenAI:
+    """
+    Drop-in replacement import for openai.OpenAI:
+
+        from cognocient import CognocientOpenAI as OpenAI
+        client = OpenAI(
+            api_key="sk-...",          # your own real OpenAI key
+            cognocient_key="sk-cog-...",  # your Cognocient proxy key, reused here
+        )
+        client.chat.completions.create(
+            model="gpt-4o", messages=[...],
+            cognocient_feature="support-bot",  # optional attribution, same field names as the proxy's X-Cost-* headers
+        )
+
+    Every method the real OpenAI client exposes still works unchanged —
+    this class only intercepts chat.completions.create() to report usage
+    after the fact; everything else is forwarded to the real client
+    untouched via attribute delegation.
+    """
+
+    def __init__(self, *args, cognocient_key: str, cognocient_ingest_url: str = DEFAULT_INGEST_URL, **kwargs):
+        try:
+            import openai
+        except ImportError as e:
+            raise ImportError(
+                "cognocient.CognocientOpenAI requires the 'openai' package. "
+                "Install it with: pip install cognocient[openai]"
+            ) from e
+
+        self._real = openai.OpenAI(*args, **kwargs)
+        self._reporter = Reporter(cognocient_key, ingest_url=cognocient_ingest_url)
+        self.chat = _ReportingChat(self._real.chat, self._reporter, "openai")
+
+    def __getattr__(self, name):
+        return getattr(self._real, name)

cognocient-0.1.0/tests/test_reporter_failure_isolation.py

@@ -0,0 +1,123 @@
+"""
+Proves the core reliability promise: if Cognocient's ingestion API is
+unreachable, the customer's real provider call still completes normally
+and no exception ever surfaces from the reporting path. Uses httpx.MockTransport
+to fake the real OpenAI/Anthropic HTTP response (so this doesn't require
+real API keys or network access to the providers), while pointing the
+reporter at a real, guaranteed-unreachable address to force an actual
+connection failure, not a mocked one.
+"""
+
+import logging
+
+import httpx
+import pytest
+
+from cognocient import CognocientAnthropic, CognocientOpenAI
+
+# Port 1 on loopback: nothing listens there, connection is refused immediately
+# and reliably, in every environment (unlike a DNS-based "unreachable" host,
+# which can vary by network config / CI sandboxing).
+UNREACHABLE_INGEST_URL = "http://127.0.0.1:1/api/ingest/wrapper"
+
+_OPENAI_CHAT_COMPLETION_JSON = {
+    "id": "chatcmpl-test123",
+    "object": "chat.completion",
+    "created": 1700000000,
+    "model": "gpt-4o-mini",
+    "choices": [{
+        "index": 0,
+        "message": {"role": "assistant", "content": "hello from the real provider"},
+        "finish_reason": "stop",
+    }],
+    "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15},
+}
+
+_ANTHROPIC_MESSAGE_JSON = {
+    "id": "msg_test123",
+    "type": "message",
+    "role": "assistant",
+    "model": "claude-sonnet-4-6",
+    "content": [{"type": "text", "text": "hello from the real provider"}],
+    "stop_reason": "end_turn",
+    "usage": {"input_tokens": 12, "output_tokens": 6},
+}
+
+
+def _mock_transport(json_body):
+    def handler(request):
+        return httpx.Response(200, json=json_body)
+    return httpx.MockTransport(handler)
+
+
+def test_openai_call_completes_and_raises_nothing_when_ingest_unreachable(caplog):
+    mock_http_client = httpx.Client(transport=_mock_transport(_OPENAI_CHAT_COMPLETION_JSON))
+    client = CognocientOpenAI(
+        api_key="sk-test-fake",
+        http_client=mock_http_client,
+        cognocient_key="sk-cog-test",
+        cognocient_ingest_url=UNREACHABLE_INGEST_URL,
+    )
+
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "hi"}],
+        cognocient_feature="test-suite",
+    )
+
+    # The real call succeeded and its real content is unaffected by reporting.
+    assert response.choices[0].message.content == "hello from the real provider"
+    assert response.usage.prompt_tokens == 10
+
+    # Force the reporter to actually attempt (and fail) delivery right now,
+    # synchronously, rather than relying on the background timer — proves
+    # the failure is caught, not merely "not yet attempted".
+    with caplog.at_level(logging.DEBUG, logger="cognocient"):
+        client._reporter.flush()  # must not raise
+    assert any("failed to report" in r.message for r in caplog.records)
+
+
+def test_anthropic_call_completes_and_raises_nothing_when_ingest_unreachable(caplog):
+    mock_http_client = httpx.Client(transport=_mock_transport(_ANTHROPIC_MESSAGE_JSON))
+    client = CognocientAnthropic(
+        api_key="sk-ant-test-fake",
+        http_client=mock_http_client,
+        cognocient_key="sk-cog-test",
+        cognocient_ingest_url=UNREACHABLE_INGEST_URL,
+    )
+
+    response = client.messages.create(
+        model="claude-sonnet-4-6",
+        max_tokens=1024,
+        messages=[{"role": "user", "content": "hi"}],
+        cognocient_feature="test-suite",
+    )
+
+    assert response.content[0].text == "hello from the real provider"
+    assert response.usage.input_tokens == 12
+
+    with caplog.at_level(logging.DEBUG, logger="cognocient"):
+        client._reporter.flush()
+    assert any("failed to report" in r.message for r in caplog.records)
+
+
+def test_report_queue_full_drops_silently_without_raising():
+    reporter_client = CognocientOpenAI(
+        api_key="sk-test-fake",
+        http_client=httpx.Client(transport=_mock_transport(_OPENAI_CHAT_COMPLETION_JSON)),
+        cognocient_key="sk-cog-test",
+        cognocient_ingest_url=UNREACHABLE_INGEST_URL,
+    )
+    reporter = reporter_client._reporter
+    # Stop the background thread so the queue can't drain on its own, then
+    # fill it past capacity to force queue.Full on the caller's own thread.
+    reporter._stop = True
+    reporter._wake.set()
+    reporter._thread.join(timeout=2.0)
+
+    from cognocient import CallReport
+    for _ in range(reporter._queue.maxsize + 10):
+        reporter.report(CallReport(
+            model="gpt-4o-mini", provider="openai",
+            prompt_tokens=1, completion_tokens=1, latency_ms=1,
+        ))  # must never raise, even once the queue is full

cognocient-0.1.0/tests/test_smoke_current_sdks.py

@@ -0,0 +1,66 @@
+"""
+Basic interface smoke test against whatever OpenAI/Anthropic SDK versions
+are actually installed (pip install cognocient[dev] pulls the current
+releases, unpinned) — catches a breaking upstream interface change before
+a customer hits it in production, not after. Run in CI on every push via
+.github/workflows/python_wrapper_smoke_test.yml.
+
+Deliberately does NOT hit real provider APIs — only checks that the real
+SDK objects still expose the attributes this wrapper's delegation depends
+on (client.chat.completions.create, client.messages.create, response.usage
+field names), which is exactly the kind of change that would silently
+break this wrapper without raising an ImportError.
+"""
+
+import inspect
+
+import anthropic
+import openai
+
+from cognocient import CognocientAnthropic, CognocientOpenAI
+from cognocient._tags import TAG_KWARGS, pop_tags
+
+
+def test_openai_sdk_still_exposes_expected_interface():
+    real_client = openai.OpenAI(api_key="sk-test-fake")
+    assert hasattr(real_client, "chat")
+    assert hasattr(real_client.chat, "completions")
+    assert callable(real_client.chat.completions.create)
+
+    sig = inspect.signature(real_client.chat.completions.create)
+    assert "model" in sig.parameters
+    assert "messages" in sig.parameters
+
+
+def test_anthropic_sdk_still_exposes_expected_interface():
+    real_client = anthropic.Anthropic(api_key="sk-ant-test-fake")
+    assert hasattr(real_client, "messages")
+    assert callable(real_client.messages.create)
+
+    sig = inspect.signature(real_client.messages.create)
+    assert "model" in sig.parameters
+    assert "messages" in sig.parameters
+    assert "max_tokens" in sig.parameters
+
+
+def test_cognocient_openai_delegates_unknown_attributes_to_real_client():
+    client = CognocientOpenAI(api_key="sk-test-fake", cognocient_key="sk-cog-test")
+    # models, embeddings, etc. are not specially wrapped — must still resolve
+    # via __getattr__ delegation to the real underlying client.
+    assert client.models is client._real.models
+    assert client.embeddings is client._real.embeddings
+
+
+def test_cognocient_anthropic_delegates_unknown_attributes_to_real_client():
+    client = CognocientAnthropic(api_key="sk-ant-test-fake", cognocient_key="sk-cog-test")
+    assert client.completions is client._real.completions
+
+
+def test_tag_kwargs_never_reach_the_real_sdk_call():
+    kwargs = {"model": "gpt-4o", "cognocient_feature": "x", "cognocient_run_id": "run_1"}
+    tags = pop_tags(kwargs)
+    assert tags == {"tag_feature": "x", "run_id": "run_1"}
+    # Every cognocient_* kwarg must be stripped before the real SDK sees kwargs,
+    # since neither real SDK accepts them and would raise a TypeError.
+    assert not any(k in kwargs for k in TAG_KWARGS)
+    assert kwargs == {"model": "gpt-4o"}