cognocient 0.1.0__py3-none-any.whl

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/_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/_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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,9 @@
+cognocient/__init__.py,sha256=wiWFp6g7jGFrR6AdS0R2LtpAAvSBs9CQmktaXyJ3RFE,285
+cognocient/_reporter.py,sha256=mdcNNj7AOKKVb7aq-Uk20P8DO5D_Ra31Y-pUu_pone4,5160
+cognocient/_tags.py,sha256=TJla6jqcBZZi2q_CuNtb6F4Goy6NPdtH1LvF5u_7qqU,1038
+cognocient/anthropic_wrapper.py,sha256=cETjM20wJf-Q6Q0FMopCl-ksA_ILFWFSq6zTj1N7nLo,3316
+cognocient/openai_wrapper.py,sha256=rOZmN3eDIGcGp80MDQfkUEWrbgry5jopNvo6tB3Y2WY,5150
+cognocient-0.1.0.dist-info/METADATA,sha256=oRLapIa4hC8FpsWlhe6639gXscR-zuXAO9tOXTOQ7jo,5609
+cognocient-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+cognocient-0.1.0.dist-info/licenses/LICENSE,sha256=qlYye1b2g2NDMrkTcarAdqVSNzUB31iShDBWUH24RWw,1067
+cognocient-0.1.0.dist-info/RECORD,,

cognocient-0.1.0.dist-info/WHEEL

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

cognocient-0.1.0.dist-info/licenses/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.