cogno-synapse 0.1.0__tar.gz

cogno_synapse-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 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 2026 Sudoers AI
+
+   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.

cogno_synapse-0.1.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: cogno-synapse
+Version: 0.1.0
+Summary: Model-transport layer for the Cogno cognitive pipeline — LLM + embedding backend protocols, Ollama + cloud backends, a single-backend factory, and a resilient fallback chain
+Author: Vinicius Vale
+Maintainer: Sudoers AI
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/sudoers-ai/cogno-synapse
+Project-URL: Repository, https://github.com/sudoers-ai/cogno-synapse
+Project-URL: Issues, https://github.com/sudoers-ai/cogno-synapse/issues
+Keywords: llm,embeddings,ollama,openai,anthropic,fallback,agents,function-calling
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.20.0
+Requires-Dist: cogno-homeo<0.2,>=0.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == "openai"
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.34; extra == "anthropic"
+Provides-Extra: groq
+Requires-Dist: groq>=0.9; extra == "groq"
+Provides-Extra: gemini
+Requires-Dist: google-genai>=0.3; extra == "gemini"
+Provides-Extra: bedrock
+Requires-Dist: boto3>=1.34; extra == "bedrock"
+Provides-Extra: llm
+Requires-Dist: openai>=1.0; extra == "llm"
+Requires-Dist: anthropic>=0.34; extra == "llm"
+Requires-Dist: groq>=0.9; extra == "llm"
+Requires-Dist: google-genai>=0.3; extra == "llm"
+Requires-Dist: boto3>=1.34; extra == "llm"
+Dynamic: license-file
+
+# cogno-synapse
+
+**Model-transport layer for the [Cogno](https://github.com/sudoers-ai/cogno-anima) cognitive pipeline** — LLM + embedding backend protocols, Ollama + cloud backends, a single-backend factory, and a resilient fallback chain.
+
+Named for the *synapse*: the junction that carries the signal between neurons. Where [`cogno-anima`](https://github.com/sudoers-ai/cogno-anima) is the *mind* and [`cogno-engram`](https://github.com/sudoers-ai/cogno-engram) is the *memory*, `cogno-synapse` is the **channel the mind speaks to language/embedding models through**.
+
+> Status: **alpha** — extracted from `cogno-anima`'s `llm/` package; unit suite (mocked SDKs) in place.
+
+## Protocol first, implementation optional
+
+The light, stable contract everyone shares is a set of structurally-typed `Protocol`s (no inheritance required):
+
+- `LLMBackend` — `async generate(system, prompt) -> (text, tokens_in, tokens_out)` + a `model` attr.
+- `ToolCallingBackend` (extends `LLMBackend`) — adds `chat_with_tools(...)` + `supports_native_tools()` for native function calling. **Separate and optional**, so a text-only backend (a stub, a distilled student) satisfies only `LLMBackend`.
+- `Embedder` — `async embed(text) -> list[float]`, `async similarity(a, b) -> float`.
+
+The heavy concrete cloud backends are **optional extras** (lazy-imported SDKs) — depend on the protocol, install only the providers you use:
+
+```bash
+pip install cogno-synapse                       # protocols + Ollama + OpenAI-compatible HTTP + fallback (httpx only)
+pip install "cogno-synapse[openai]"             # + OpenAI SDK
+pip install "cogno-synapse[anthropic|groq|gemini|bedrock]"
+pip install "cogno-synapse[llm]"                # all cloud SDKs
+```
+
+## Backends
+
+`OllamaBackend`/`OllamaEmbedder` (local, `think=false` by default so reasoning models still return direct JSON), plus `OpenAIBackend`, `AnthropicBackend`, `GroqBackend`, `GeminiBackend`, `BedrockBackend` — each implements `LLMBackend` + `ToolCallingBackend`. OpenAI-compatible providers (DeepSeek, Moonshot, xAI/Grok, OpenRouter, Together, Fireworks) reuse `OpenAIBackend` via `base_url`; `create_backend("provider:model")` instantiates one by string. Backends **raise** on transport/auth failure (`InvalidAPIKeyError` for 401/403) rather than degrading silently.
+
+`CachingEmbedder` wraps any `Embedder` with a bounded LRU + token accounting (`EmbeddingUsage`). `parse_tool_calls_from_text` reads `<TOOL_CALL>` tags for the text-fallback function-calling path (and rescues FC leaks).
+
+## Resilient fallback — over `cogno-homeo`
+
+`FallbackBackend` tries an ordered chain, first success wins, last error propagates. The loop runs on [`cogno-homeo`](https://github.com/sudoers-ai/cogno-homeo)'s `resilient_call`, so you can opt into a circuit breaker, retry/backoff, and a metrics seam — with none supplied it behaves like the historical "try each once" chain:
+
+```python
+from cogno_synapse import FallbackBackend, create_backend
+from cogno_homeo import CircuitBreaker, RetryPolicy
+
+chain = FallbackBackend(
+    [create_backend("openai:gpt-4o-mini"), create_backend("groq:llama-3.1-8b-instant")],
+    breaker=CircuitBreaker(), policy=RetryPolicy(max_retries=2),   # optional
+)
+text, tin, tout = await chain.generate(system, prompt)
+```
+
+## Scope
+
+This library is **transport only** — it produces raw token counts but does not price them (the host does), and it carries no business model-ladder/`_FALLBACK_MATRIX` (also host). Resilience is delegated to `cogno-homeo`; cognition lives in `cogno-anima`.
+
+## The Cogno ecosystem
+
+`cogno-synapse` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete
+conversational-agent platform. Each library owns a single concern and stays
+infra-agnostic; a **host** assembles them into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins
+them. Our reference host — `cogno-host`, with its `cogno-ui` dashboard — is the
+private product layer, but it holds no special powers: everything it does rides
+on the public seams documented in each library's `docs/HOST_INTEGRATION.md`, so
+you can assemble a body of your own.
+
+## Test
+
+```bash
+pip install -e ".[dev]"      # unit tests mock every SDK — no cloud keys needed
+pytest tests/unit -q
+```

cogno_synapse-0.1.0/README.md

@@ -0,0 +1,71 @@
+# cogno-synapse
+
+**Model-transport layer for the [Cogno](https://github.com/sudoers-ai/cogno-anima) cognitive pipeline** — LLM + embedding backend protocols, Ollama + cloud backends, a single-backend factory, and a resilient fallback chain.
+
+Named for the *synapse*: the junction that carries the signal between neurons. Where [`cogno-anima`](https://github.com/sudoers-ai/cogno-anima) is the *mind* and [`cogno-engram`](https://github.com/sudoers-ai/cogno-engram) is the *memory*, `cogno-synapse` is the **channel the mind speaks to language/embedding models through**.
+
+> Status: **alpha** — extracted from `cogno-anima`'s `llm/` package; unit suite (mocked SDKs) in place.
+
+## Protocol first, implementation optional
+
+The light, stable contract everyone shares is a set of structurally-typed `Protocol`s (no inheritance required):
+
+- `LLMBackend` — `async generate(system, prompt) -> (text, tokens_in, tokens_out)` + a `model` attr.
+- `ToolCallingBackend` (extends `LLMBackend`) — adds `chat_with_tools(...)` + `supports_native_tools()` for native function calling. **Separate and optional**, so a text-only backend (a stub, a distilled student) satisfies only `LLMBackend`.
+- `Embedder` — `async embed(text) -> list[float]`, `async similarity(a, b) -> float`.
+
+The heavy concrete cloud backends are **optional extras** (lazy-imported SDKs) — depend on the protocol, install only the providers you use:
+
+```bash
+pip install cogno-synapse                       # protocols + Ollama + OpenAI-compatible HTTP + fallback (httpx only)
+pip install "cogno-synapse[openai]"             # + OpenAI SDK
+pip install "cogno-synapse[anthropic|groq|gemini|bedrock]"
+pip install "cogno-synapse[llm]"                # all cloud SDKs
+```
+
+## Backends
+
+`OllamaBackend`/`OllamaEmbedder` (local, `think=false` by default so reasoning models still return direct JSON), plus `OpenAIBackend`, `AnthropicBackend`, `GroqBackend`, `GeminiBackend`, `BedrockBackend` — each implements `LLMBackend` + `ToolCallingBackend`. OpenAI-compatible providers (DeepSeek, Moonshot, xAI/Grok, OpenRouter, Together, Fireworks) reuse `OpenAIBackend` via `base_url`; `create_backend("provider:model")` instantiates one by string. Backends **raise** on transport/auth failure (`InvalidAPIKeyError` for 401/403) rather than degrading silently.
+
+`CachingEmbedder` wraps any `Embedder` with a bounded LRU + token accounting (`EmbeddingUsage`). `parse_tool_calls_from_text` reads `<TOOL_CALL>` tags for the text-fallback function-calling path (and rescues FC leaks).
+
+## Resilient fallback — over `cogno-homeo`
+
+`FallbackBackend` tries an ordered chain, first success wins, last error propagates. The loop runs on [`cogno-homeo`](https://github.com/sudoers-ai/cogno-homeo)'s `resilient_call`, so you can opt into a circuit breaker, retry/backoff, and a metrics seam — with none supplied it behaves like the historical "try each once" chain:
+
+```python
+from cogno_synapse import FallbackBackend, create_backend
+from cogno_homeo import CircuitBreaker, RetryPolicy
+
+chain = FallbackBackend(
+    [create_backend("openai:gpt-4o-mini"), create_backend("groq:llama-3.1-8b-instant")],
+    breaker=CircuitBreaker(), policy=RetryPolicy(max_retries=2),   # optional
+)
+text, tin, tout = await chain.generate(system, prompt)
+```
+
+## Scope
+
+This library is **transport only** — it produces raw token counts but does not price them (the host does), and it carries no business model-ladder/`_FALLBACK_MATRIX` (also host). Resilience is delegated to `cogno-homeo`; cognition lives in `cogno-anima`.
+
+## The Cogno ecosystem
+
+`cogno-synapse` is one organ of **[Cogno](https://github.com/sudoers-ai)** — a family of
+small, composable, Apache-2.0 libraries that together form a complete
+conversational-agent platform. Each library owns a single concern and stays
+infra-agnostic; a **host** assembles them into a running agent:
+
+![The Cogno ecosystem](docs/assets/cogno-ecosystem.svg)
+
+The open-source libraries are the organs; the **host is the body** that joins
+them. Our reference host — `cogno-host`, with its `cogno-ui` dashboard — is the
+private product layer, but it holds no special powers: everything it does rides
+on the public seams documented in each library's `docs/HOST_INTEGRATION.md`, so
+you can assemble a body of your own.
+
+## Test
+
+```bash
+pip install -e ".[dev]"      # unit tests mock every SDK — no cloud keys needed
+pytest tests/unit -q
+```

cogno_synapse-0.1.0/cogno_synapse/__init__.py

@@ -0,0 +1,58 @@
+"""
+cogno-synapse — the model-transport layer of the Cogno stack.
+
+Named for the *synapse*: the junction that carries the signal between neurons.
+Where cogno-anima is the mind and cogno-engram is the memory, cogno-synapse is
+the channel the mind speaks to language/embedding models through — a set of
+structurally-typed backend protocols plus concrete implementations (Ollama +
+cloud providers), a single-backend factory, a resilient fallback chain, and the
+text-fallback tool-call parser.
+
+The protocols are the light, stable contract everyone shares; the concrete cloud
+backends are optional extras (lazy-imported SDKs). Resilience (breaker/retry/
+metrics) is delegated to cogno-homeo.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _dist_version
+
+try:
+    __version__ = _dist_version("cogno-synapse")
+except PackageNotFoundError:  # source tree without an installed dist (e.g. vendored checkout)
+    __version__ = "0.0.0"
+
+
+from cogno_synapse.base import LLMBackend, ToolCallingBackend, Embedder
+from cogno_synapse.ollama import OllamaBackend, OllamaEmbedder
+from cogno_synapse.cache import CachingEmbedder, EmbeddingUsage
+from cogno_synapse.tool_parsing import parse_tool_calls_from_text
+from cogno_synapse.openai_backend import OpenAIBackend
+from cogno_synapse.anthropic_backend import AnthropicBackend
+from cogno_synapse.groq_backend import GroqBackend
+from cogno_synapse.gemini_backend import GeminiBackend
+from cogno_synapse.bedrock_backend import BedrockBackend
+from cogno_synapse.fallback import FallbackBackend
+from cogno_synapse.factory import create_backend, parse_model_string
+from cogno_synapse.errors import SynapseError, MissingAPIKeyError, InvalidAPIKeyError
+
+__all__ = [
+    "LLMBackend",
+    "ToolCallingBackend",
+    "Embedder",
+    "OllamaBackend",
+    "OllamaEmbedder",
+    "CachingEmbedder",
+    "EmbeddingUsage",
+    "parse_tool_calls_from_text",
+    "OpenAIBackend",
+    "AnthropicBackend",
+    "GroqBackend",
+    "GeminiBackend",
+    "BedrockBackend",
+    "FallbackBackend",
+    "create_backend",
+    "parse_model_string",
+    "SynapseError",
+    "MissingAPIKeyError",
+    "InvalidAPIKeyError",
+]

cogno_synapse-0.1.0/cogno_synapse/_math.py

@@ -0,0 +1,21 @@
+"""Tiny pure-Python vector math used by the embedding backends/cache.
+
+Vendored (not imported from a sibling) so cogno-synapse stays free of any
+cogno-anima dependency — this is a self-contained 10-line helper.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+def cosine_similarity(v1: list[float], v2: list[float]) -> float:
+    """Calculates cosine similarity between two vector lists in pure Python."""
+    if not v1 or not v2 or len(v1) != len(v2):
+        return 0.0
+    dot_product = sum(a * b for a, b in zip(v1, v2))
+    magnitude_v1 = math.sqrt(sum(a * a for a in v1))
+    magnitude_v2 = math.sqrt(sum(b * b for b in v2))
+    if magnitude_v1 == 0.0 or magnitude_v2 == 0.0:
+        return 0.0
+    return dot_product / (magnitude_v1 * magnitude_v2)

cogno_synapse-0.1.0/cogno_synapse/_obs.py

@@ -0,0 +1,59 @@
+"""
+cogno_synapse._obs — tiny logging helpers shared by the backends.
+
+Keeps the ``key=value`` log lines byte-identical across the six backends without
+a logging framework. Per LOGGING.md: libs emit, the host configures. INFO marks
+the (relatively expensive) "call finished" milestone; WARNING flags a recoverable
+transport error (429/5xx) just before it propagates to a ``FallbackBackend``;
+the request body goes to DEBUG only (dev-only — it carries user content/PII), and
+the ``api_key`` is never logged.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+# HTTP statuses worth a WARNING (rate limit / transient upstream) before re-raise.
+_RETRYABLE_STATUS = frozenset({429, 500, 502, 503, 504})
+
+
+def status_of(exc: Exception) -> Any:
+    """Best-effort HTTP status from an SDK/httpx exception (None if absent)."""
+    direct = getattr(exc, "status_code", None) or getattr(exc, "http_status", None)
+    if direct is not None:
+        return direct
+    resp = getattr(exc, "response", None)
+    return getattr(resp, "status_code", None)
+
+
+def is_retryable(exc: Exception) -> bool:
+    return status_of(exc) in _RETRYABLE_STATUS
+
+
+def log_request(logger: logging.Logger, provider: str, model: str, system: str, prompt: str) -> None:
+    """DEV-ONLY full request trace (DEBUG). Carries user content — never on in prod."""
+    if logger.isEnabledFor(logging.DEBUG):
+        logger.debug(
+            "event=generate provider=%s model=%s system_len=%d prompt_len=%d prompt=%s",
+            provider, model, len(system), len(prompt), prompt,
+        )
+
+
+def log_done(
+    logger: logging.Logger, provider: str, model: str, t0: float, tokens_in: int, tokens_out: int
+) -> None:
+    logger.info(
+        "event=generate_done provider=%s model=%s latency_ms=%.1f tokens_in=%d tokens_out=%d",
+        provider, model, (time.perf_counter() - t0) * 1000.0, tokens_in, tokens_out,
+    )
+
+
+def warn_if_retryable(logger: logging.Logger, provider: str, model: str, exc: Exception) -> None:
+    """WARNING on a recoverable transport error before it propagates (fallback catches)."""
+    if is_retryable(exc):
+        logger.warning(
+            "event=generate_retryable provider=%s model=%s status=%s error=%s",
+            provider, model, status_of(exc), exc,
+        )