e-volv-logs 0.1.0__tar.gz

e_volv_logs-0.1.0/.gitignore

@@ -0,0 +1,145 @@
+# See https://docs.github.com/en/get-started/getting-started-with-git/ignoring-files for more about ignoring files.
+
+# compiled output
+dist
+tmp
+out-tsc
+
+# dependencies
+node_modules
+
+# IDEs and editors
+/.idea
+.project
+.classpath
+.c9/
+*.launch
+.settings/
+*.sublime-workspace
+
+# IDE - VSCode
+.vscode/*
+!.vscode/settings.json
+!.vscode/tasks.json
+!.vscode/launch.json
+!.vscode/extensions.json
+
+# misc
+/.sass-cache
+/connect.lock
+/coverage
+/libpeerconnection.log
+npm-debug.log
+yarn-error.log
+testem.log
+/typings
+
+# System Files
+.DS_Store
+Thumbs.db
+
+.nx/cache
+.nx/workspace-data
+.cursor/rules/nx-rules.mdc
+.github/instructions/nx.instructions.md
+
+.claude/worktrees
+.claude/settings.local.json
+.nx/polygraph
+
+# Next.js
+.next
+out
+# Terraform
+infra/.terraform/
+infra/*.tfstate
+infra/*.tfstate.backup
+# Terraform writes rollback copies as terraform.tfstate.<epoch>.backup, which
+# the pattern above does not match — the timestamp sits before `.backup`. One
+# such file was sitting untracked on 2026-08-09 holding 68 plaintext
+# secret_data values (Surreal password, JWT secret, vault key, Stripe live key,
+# GitHub App private key), fully stageable by `git add -A`.
+infra/*.tfstate.*.backup
+infra/terraform.tfvars
+# Any sibling of the real tfvars — .bak, .orig, .save, dated copies. The exact
+# path above does not match them, so an editor backup or a hand-rolled copy of
+# a file holding every production secret lands in `git status` as untracked and
+# would be staged by `git add -A`. Nearly happened on 2026-08-09.
+infra/terraform.tfvars.*
+!infra/terraform.tfvars.example
+infra/.terraform.lock.hcl
+
+# Environment files — never commit; contain live credentials
+.env
+.env.local
+
+# Untracked 2026-08-07: this working copy accumulates real credential values as
+# the remediation gates are worked through, so it cannot be a tracked file.
+# The sanitised instructions live in docs/GATE-2-CREDENTIALS.md, which stays
+# tracked and must never carry a real value.
+docs/PRODUCTION-FIX-PLAN.md
+.env.*.local
+apps/*/.env
+apps/*/.env.local
+
+# Python bytecode caches
+__pycache__/
+*.pyc
+
+# Nx/TS incremental build info
+apps/evolve-backend/tsconfig.tsbuildinfo
+
+# Test output (nx python targets write here)
+reports/
+
+# Terraform plan files embed sensitive variable values — never commit them.
+# `-out=` takes an arbitrary name, so the two patterns below only catch plans a
+# person happened to call "tfplan". Files named tfdom/tfgh/tfpost were found
+# untracked on 2026-08-09. Plans are zip archives, so a name-based rule is the
+# only defence — hence the explicit directory below for anything ad hoc.
+infra/tfplan
+infra/*.tfplan
+infra/tf-plans/
+
+# Playwright MCP writes browser console logs, traces and screenshots here when
+# an agent drives the app. Session artefacts, not source — and they capture
+# whatever the logged-in page happened to print, so they do not belong in git.
+.playwright-mcp/
+
+# Coverage artefacts — rewritten by every test run, never useful in a diff.
+apps/evolve-ai/.coverage
+test-output
+
+# E2E build/output artefacts
+apps/*-e2e/out-tsc/
+apps/*-e2e/test-output/
+playwright-report/
+test-results/
+
+# Memtrace (local code index — machine-local, never committed)
+.memdb/
+.memtrace/
+.memtrace-workspace
+
+# Local MCP server config — holds a Memtrace licence key.
+.mcp.json
+
+# Written by the Firebase Auth emulator that docs/E2E-TESTING.md tells you to start.
+firebase-debug.log
+firestore-debug.log
+ui-debug.log
+
+# TypeScript incremental build state (packages/logs-js writes one at its root).
+*.tsbuildinfo
+.logs-keys.json
+.logs-keys-mspeed.json
+
+# Recording rig: a saved production session, equivalent to a password.
+tools/record/.auth/
+
+# Recording rig: raw .webm captures and crop manifests. Only the rendered
+# mp4/jpg under public/media/tour is kept.
+tools/record/out/
+
+# Recording rig scratch probes.
+tools/record/*.tmp.ts

e_volv_logs-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: e-volv-logs
+Version: 0.1.0
+Summary: Evolve Log Manager SDK — logs, traces and error capture for Python.
+Project-URL: Homepage, https://github.com/Pactify-Pty-Ltd/theevolve/tree/main/packages/logs-py
+Project-URL: Source, https://github.com/Pactify-Pty-Ltd/theevolve
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: langchain
+Requires-Dist: langchain-core>=0.3; extra == 'langchain'
+Description-Content-Type: text/markdown
+
+# e-volv-logs
+
+Evolve Log Manager SDK for Python — batched log shipping, trace context and
+error capture against the Evolve ingest endpoint
+(`POST /api/public/v1/logs`). Companion: the Node.js SDK `@e-volv/logs`.
+
+Python 3.10+.
+
+```bash
+pip install e-volv-logs
+```
+
+## Quick start
+
+```python
+import e_volv_logs as evolve_logs
+from e_volv_logs import init, log, span, trace
+
+init(
+    key="evk_…",  # project ingest key
+    url="https://your-host/api/public/v1/logs",
+    service="api",
+    environment="production",
+    release="1.4.2",
+)
+
+log.info("order created", {"orderId": "o_1", "total": 42.5})
+log.error("payment failed", {"orderId": "o_1"})
+
+try:
+    await charge()
+except Exception as err:
+    log.exception(err, {"orderId": "o_1"})  # exception.type/message/stack
+
+# Traces live in contextvars — they flow across await. httpx/requests
+# requests made inside a trace get a W3C traceparent header automatically.
+with trace():
+    with span("db.query", {"table": "orders"}):
+        await db.query("SELECT …")
+    await httpx.get("https://internal/svc")  # traceparent injected
+```
+
+If `key` or `url` is missing, `init()` returns a no-op client and warns once.
+The SDK never raises into user code.
+
+## Batching, retries, drops
+
+- Flushes at **200 events**, **2 s** (age of the oldest buffered event), or a
+  **512 KB** payload — whichever comes first. Bodies are gzipped
+  (`Content-Encoding: gzip`).
+- **429** retries with exponential backoff (0.5 s doubling, capped at 10 s),
+  up to 3 attempts. **413** halves the batch and retries.
+- When the pending buffer exceeds **2× batch size**, the **oldest** events are
+  dropped; losses are visible on `client.dropped`.
+- `atexit` flushes whatever is pending.
+
+## Options
+
+`init(key=, url=, service=, environment=, release=, redact_keys=[...],
+sample_rate=1.0, capture_excepthook=True)` — `redact_keys` are merged into the
+backstop regex `password|secret|token|authorization|cookie|set-cookie|api[-_]?key`
+(case-insensitive), applied to attrs before queueing.
+
+## stdlib logging
+
+```python
+import logging
+from e_volv_logs import init, LogHandler
+
+init(key="evk_…", url="…", service="api")
+logging.getLogger("myapp").addHandler(LogHandler())
+```
+
+Levels map to OTel severities (DEBUG→5, INFO→9, WARNING→13, ERROR→17,
+CRITICAL→21). `extra={...}` on the log call becomes event attrs; `exc_info`
+becomes `exception.*` fields. `sys.excepthook` capture is on by default.
+
+## FastAPI / Starlette
+
+```python
+from e_volv_logs.integrations.fastapi import EvolveLogsMiddleware
+
+app.add_middleware(EvolveLogsMiddleware)  # one root span per request
+```
+
+The middleware continues the trace when the inbound request carries an
+`x-evolve-traceparent` header (Evolve backend → evolve-ai propagation),
+otherwise starts a fresh root trace.
+
+## LangChain and LangGraph
+
+```bash
+pip install "e-volv-logs[langchain]"
+```
+
+```python
+from e_volv_logs.integrations.langchain import EvolveLogsCallbackHandler
+
+result = graph.invoke(
+    {"question": "…"},
+    config={"callbacks": [EvolveLogsCallbackHandler()]},
+)
+```
+
+One span per LangChain run, nested by `parent_run_id`, all sharing one trace —
+so a LangGraph node's tool calls and model calls appear inside the node on the
+Evolve trace graph. Span names:
+
+| Callback                               | Span name      |
+| -------------------------------------- | -------------- |
+| `on_chain_start` with `langgraph_node` | `graph.<node>` |
+| `on_chain_start` otherwise             | `chain.<name>` |
+| `on_tool_start`                        | `tool.<name>`  |
+| `on_llm_start` / `on_chat_model_start` | `llm.<model>`  |
+
+Errors end the span through `_log_span_error` (severity error, `exception.*`
+attrs), exactly like `span()` raised inside a body.
+
+## Queue hops
+
+A span on the consumer side joins the producer's trace only if the traceparent
+travels with the job:
+
+```python
+from e_volv_logs import run_with_traceparent, span, traceparent
+
+# producer
+queue.enqueue(work, payload, trace=traceparent())
+
+# consumer: the body runs as a new hop of the producer's trace.
+with run_with_traceparent(job.trace), span("queue.work", {"queue": "work"}):
+    handle(job)
+```
+
+`run_with_traceparent(header)` parses a W3C traceparent; an absent or malformed
+header starts a fresh trace, so a producer that sends nothing still yields a
+trace of its own.
+
+## Development
+
+```bash
+cd packages/logs-py
+uv sync
+uv run pytest tests/ -q
+```

e_volv_logs-0.1.0/README.md

@@ -0,0 +1,145 @@
+# e-volv-logs
+
+Evolve Log Manager SDK for Python — batched log shipping, trace context and
+error capture against the Evolve ingest endpoint
+(`POST /api/public/v1/logs`). Companion: the Node.js SDK `@e-volv/logs`.
+
+Python 3.10+.
+
+```bash
+pip install e-volv-logs
+```
+
+## Quick start
+
+```python
+import e_volv_logs as evolve_logs
+from e_volv_logs import init, log, span, trace
+
+init(
+    key="evk_…",  # project ingest key
+    url="https://your-host/api/public/v1/logs",
+    service="api",
+    environment="production",
+    release="1.4.2",
+)
+
+log.info("order created", {"orderId": "o_1", "total": 42.5})
+log.error("payment failed", {"orderId": "o_1"})
+
+try:
+    await charge()
+except Exception as err:
+    log.exception(err, {"orderId": "o_1"})  # exception.type/message/stack
+
+# Traces live in contextvars — they flow across await. httpx/requests
+# requests made inside a trace get a W3C traceparent header automatically.
+with trace():
+    with span("db.query", {"table": "orders"}):
+        await db.query("SELECT …")
+    await httpx.get("https://internal/svc")  # traceparent injected
+```
+
+If `key` or `url` is missing, `init()` returns a no-op client and warns once.
+The SDK never raises into user code.
+
+## Batching, retries, drops
+
+- Flushes at **200 events**, **2 s** (age of the oldest buffered event), or a
+  **512 KB** payload — whichever comes first. Bodies are gzipped
+  (`Content-Encoding: gzip`).
+- **429** retries with exponential backoff (0.5 s doubling, capped at 10 s),
+  up to 3 attempts. **413** halves the batch and retries.
+- When the pending buffer exceeds **2× batch size**, the **oldest** events are
+  dropped; losses are visible on `client.dropped`.
+- `atexit` flushes whatever is pending.
+
+## Options
+
+`init(key=, url=, service=, environment=, release=, redact_keys=[...],
+sample_rate=1.0, capture_excepthook=True)` — `redact_keys` are merged into the
+backstop regex `password|secret|token|authorization|cookie|set-cookie|api[-_]?key`
+(case-insensitive), applied to attrs before queueing.
+
+## stdlib logging
+
+```python
+import logging
+from e_volv_logs import init, LogHandler
+
+init(key="evk_…", url="…", service="api")
+logging.getLogger("myapp").addHandler(LogHandler())
+```
+
+Levels map to OTel severities (DEBUG→5, INFO→9, WARNING→13, ERROR→17,
+CRITICAL→21). `extra={...}` on the log call becomes event attrs; `exc_info`
+becomes `exception.*` fields. `sys.excepthook` capture is on by default.
+
+## FastAPI / Starlette
+
+```python
+from e_volv_logs.integrations.fastapi import EvolveLogsMiddleware
+
+app.add_middleware(EvolveLogsMiddleware)  # one root span per request
+```
+
+The middleware continues the trace when the inbound request carries an
+`x-evolve-traceparent` header (Evolve backend → evolve-ai propagation),
+otherwise starts a fresh root trace.
+
+## LangChain and LangGraph
+
+```bash
+pip install "e-volv-logs[langchain]"
+```
+
+```python
+from e_volv_logs.integrations.langchain import EvolveLogsCallbackHandler
+
+result = graph.invoke(
+    {"question": "…"},
+    config={"callbacks": [EvolveLogsCallbackHandler()]},
+)
+```
+
+One span per LangChain run, nested by `parent_run_id`, all sharing one trace —
+so a LangGraph node's tool calls and model calls appear inside the node on the
+Evolve trace graph. Span names:
+
+| Callback                               | Span name      |
+| -------------------------------------- | -------------- |
+| `on_chain_start` with `langgraph_node` | `graph.<node>` |
+| `on_chain_start` otherwise             | `chain.<name>` |
+| `on_tool_start`                        | `tool.<name>`  |
+| `on_llm_start` / `on_chat_model_start` | `llm.<model>`  |
+
+Errors end the span through `_log_span_error` (severity error, `exception.*`
+attrs), exactly like `span()` raised inside a body.
+
+## Queue hops
+
+A span on the consumer side joins the producer's trace only if the traceparent
+travels with the job:
+
+```python
+from e_volv_logs import run_with_traceparent, span, traceparent
+
+# producer
+queue.enqueue(work, payload, trace=traceparent())
+
+# consumer: the body runs as a new hop of the producer's trace.
+with run_with_traceparent(job.trace), span("queue.work", {"queue": "work"}):
+    handle(job)
+```
+
+`run_with_traceparent(header)` parses a W3C traceparent; an absent or malformed
+header starts a fresh trace, so a producer that sends nothing still yields a
+trace of its own.
+
+## Development
+
+```bash
+cd packages/logs-py
+uv sync
+uv run pytest tests/ -q
+```

e_volv_logs-0.1.0/e_volv_logs/__init__.py

@@ -0,0 +1,40 @@
+"""Evolve Log Manager SDK for Python (e-volv-logs)."""
+
+from evolve_logs import *  # noqa: F403
+from evolve_logs import (
+    FLUSH_MS,
+    MAX_BATCH,
+    MAX_PAYLOAD_BYTES,
+    SEVERITY,
+    LogHandler,
+    LogsClient,
+    current_context,
+    get_client,
+    init,
+    log,
+    patch_httpx,
+    patch_requests,
+    run_with_traceparent,
+    span,
+    trace,
+    traceparent,
+)
+
+__all__ = [
+    "FLUSH_MS",
+    "MAX_BATCH",
+    "MAX_PAYLOAD_BYTES",
+    "SEVERITY",
+    "LogHandler",
+    "LogsClient",
+    "current_context",
+    "get_client",
+    "init",
+    "log",
+    "patch_httpx",
+    "patch_requests",
+    "run_with_traceparent",
+    "span",
+    "trace",
+    "traceparent",
+]

e_volv_logs-0.1.0/e_volv_logs/integrations/__init__.py

@@ -0,0 +1,2 @@
+"""Integrations for e_volv_logs."""
+from evolve_logs.integrations import *  # noqa: F403

e_volv_logs-0.1.0/e_volv_logs/integrations/fastapi.py

@@ -0,0 +1,4 @@
+"""FastAPI integration re-export."""
+from evolve_logs.integrations.fastapi import EvolveLogsMiddleware
+
+__all__ = ["EvolveLogsMiddleware"]

e_volv_logs-0.1.0/e_volv_logs/integrations/langchain.py

@@ -0,0 +1,4 @@
+"""LangChain integration re-export."""
+from evolve_logs.integrations.langchain import EvolveLogsCallbackHandler
+
+__all__ = ["EvolveLogsCallbackHandler"]

e_volv_logs-0.1.0/evolve_logs/__init__.py

@@ -0,0 +1,95 @@
+"""Evolve Log Manager SDK for Python.
+
+Batches events (200 events / 2 s / 512 KB), gzips the payload, retries with
+backoff on 429/413, and drops oldest when the pending buffer exceeds 2x the
+batch size. Trace context lives in :mod:`contextvars`, so it flows across
+``await``. Everything is fail-silent: a logging SDK must never raise into user
+code.
+"""
+
+from evolve_logs.client import (
+    FLUSH_MS,
+    MAX_BATCH,
+    MAX_PAYLOAD_BYTES,
+    LogsClient,
+    init,
+)
+from evolve_logs.context import (
+    current_context,
+    run_with_traceparent,
+    span,
+    trace,
+    traceparent,
+)
+from evolve_logs.handler import LogHandler
+from evolve_logs.patches import patch_httpx, patch_requests
+from evolve_logs.types import SEVERITY
+
+__all__ = [
+    "FLUSH_MS",
+    "MAX_BATCH",
+    "MAX_PAYLOAD_BYTES",
+    "SEVERITY",
+    "LogHandler",
+    "LogsClient",
+    "current_context",
+    "init",
+    "log",
+    "patch_httpx",
+    "patch_requests",
+    "run_with_traceparent",
+    "span",
+    "trace",
+    "traceparent",
+]
+
+
+class _LogProxy:
+    """Module-level logger bound to the default client (set by ``init``)."""
+
+    def trace(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.trace(message, attrs)
+
+    def debug(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.debug(message, attrs)
+
+    def info(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.info(message, attrs)
+
+    def warn(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.warn(message, attrs)
+
+    warning = warn
+
+    def error(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.error(message, attrs)
+
+    def fatal(self, message, attrs=None):
+        client = get_client()
+        if client:
+            client.fatal(message, attrs)
+
+    def exception(self, err, attrs=None):
+        client = get_client()
+        if client:
+            client.exception(err, attrs)
+
+
+log = _LogProxy()
+
+
+def get_client() -> LogsClient | None:
+    """The client installed by :func:`init`, or None before init."""
+    from evolve_logs.client import get_client as _get
+
+    return _get()