weharness-tracing 0.1.1__tar.gz

weharness_tracing-0.1.1/.gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+*.tgz
+.venv/
+__pycache__/
+*.pyc
+.env
+.env.*

weharness_tracing-0.1.1/LICENSE

@@ -0,0 +1,202 @@
+
+                                 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 [yyyy] [name of copyright owner]
+
+   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.

weharness_tracing-0.1.1/PKG-INFO

@@ -0,0 +1,40 @@
+Metadata-Version: 2.5
+Name: weharness-tracing
+Version: 0.1.1
+Summary: Send your AI agent's traces to WeHarness (OpenTelemetry; metadata only unless you choose otherwise).
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: opentelemetry-api==1.45.1
+Requires-Dist: opentelemetry-exporter-otlp-proto-http==1.45.1
+Requires-Dist: opentelemetry-sdk==1.45.1
+Description-Content-Type: text/markdown
+
+# WeHarness tracing for Python
+
+Send agent, model and tool spans to WeHarness using OpenTelemetry and OTLP/HTTP.
+Requires Python 3.10 or newer and a project ingest key from the WeHarness Tracing page.
+
+```python
+import weharness_tracing as wh
+
+# Set WEHARNESS_INGEST_KEY in your server environment, never in browser code.
+wh.init(service="my-agent")
+with wh.agent_run("support"):
+    with wh.tool_call("lookup_order"):
+        pass  # Call your tool here.
+wh.shutdown()
+```
+
+The default endpoint is `https://api.weharness.io/otlp/v1/traces`.
+Override it with `WEHARNESS_OTLP_ENDPOINT` if needed. Set `WEHARNESS_REVISION`
+to correlate traces with a source revision.
+
+Known prompt, output, tool-payload and stacktrace attributes are filtered by default.
+This filter is not a general secret detector: do not put secrets or personal data in
+span names, error messages or custom metadata. Content capture requires explicit
+configuration and appropriate project settings. An ingest key sends traces; it does
+not authorize reading them.
+
+An existing OpenTelemetry tracer provider is reused. Background batches are bounded;
+call `shutdown()` to flush pending spans before the process exits.

weharness_tracing-0.1.1/README.md

@@ -0,0 +1,28 @@
+# WeHarness tracing for Python
+
+Send agent, model and tool spans to WeHarness using OpenTelemetry and OTLP/HTTP.
+Requires Python 3.10 or newer and a project ingest key from the WeHarness Tracing page.
+
+```python
+import weharness_tracing as wh
+
+# Set WEHARNESS_INGEST_KEY in your server environment, never in browser code.
+wh.init(service="my-agent")
+with wh.agent_run("support"):
+    with wh.tool_call("lookup_order"):
+        pass  # Call your tool here.
+wh.shutdown()
+```
+
+The default endpoint is `https://api.weharness.io/otlp/v1/traces`.
+Override it with `WEHARNESS_OTLP_ENDPOINT` if needed. Set `WEHARNESS_REVISION`
+to correlate traces with a source revision.
+
+Known prompt, output, tool-payload and stacktrace attributes are filtered by default.
+This filter is not a general secret detector: do not put secrets or personal data in
+span names, error messages or custom metadata. Content capture requires explicit
+configuration and appropriate project settings. An ingest key sends traces; it does
+not authorize reading them.
+
+An existing OpenTelemetry tracer provider is reused. Background batches are bounded;
+call `shutdown()` to flush pending spans before the process exits.

weharness_tracing-0.1.1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "weharness-tracing"
+version = "0.1.1"
+readme = "README.md"
+license = "Apache-2.0"
+license-files = ["LICENSE"]
+description = "Send your AI agent's traces to WeHarness (OpenTelemetry; metadata only unless you choose otherwise)."
+requires-python = ">=3.10"
+dependencies = [
+    "opentelemetry-api==1.45.1",
+    "opentelemetry-sdk==1.45.1",
+    "opentelemetry-exporter-otlp-proto-http==1.45.1",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/weharness_tracing"]

weharness_tracing-0.1.1/src/weharness_tracing/__init__.py

@@ -0,0 +1,182 @@
+"""Send your AI agent's traces to WeHarness.
+
+    import weharness_tracing as wh
+
+    wh.init(service="refund-agent")               # key from WEHARNESS_INGEST_KEY
+    with wh.agent_run("refunds"):
+        with wh.model_call("gemini-3.8-flash", provider="gcp.gemini") as call:
+            ...
+            call.usage(input_tokens=120, output_tokens=40)
+        with wh.tool_call("lookup_order"):
+            ...
+    wh.shutdown()                                  # flush before the process ends
+
+It is plain OpenTelemetry (GenAI semantic conventions), sent over OTLP/HTTP with your project's ingest key:
+- Your existing OpenTelemetry setup keeps working. When the application already has an SDK tracer provider, WeHarness
+  adds its exporter to it instead of replacing it; any instrumentation you use is sent too.
+- Metadata only by default: prompts, model outputs, tool arguments and results, and bodies are removed before they
+  leave the process (WeHarness's gateway removes them again unless the project agreed to keep content).
+- Spans go in bounded background batches with retries; a slow or unreachable WeHarness never blocks your agent.
+- The code version comes from WEHARNESS_REVISION or the usual CI variables (GITHUB_SHA, …), so WeHarness can match a
+  trace with the change that produced it.
+"""
+
+import os
+import sys
+from contextlib import contextmanager
+
+from opentelemetry import trace
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import Event, ReadableSpan, TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor, SpanExporter
+
+__all__ = ["init", "agent_run", "model_call", "tool_call", "shutdown", "CONTENT"]
+__version__ = "0.1.0"
+
+ENDPOINT = "https://api.weharness.io/otlp/v1/traces"
+REVISION_VARIABLES = ("WEHARNESS_REVISION", "GITHUB_SHA", "CI_COMMIT_SHA", "VERCEL_GIT_COMMIT_SHA", "RENDER_GIT_COMMIT",
+                      "SOURCE_VERSION", "GIT_COMMIT")
+# What is content rather than metadata (the same list as WeHarness's gateway).
+CONTENT = ("gen_ai.prompt", "gen_ai.completion", "gen_ai.input.messages", "gen_ai.output.messages",
+           "gen_ai.system_instructions", "gen_ai.tool.call.arguments", "gen_ai.tool.call.result", "gen_ai.content.",
+           "input.value", "output.value", "llm.input_messages", "llm.output_messages", "llm.prompts",
+           "traceloop.entity.input", "traceloop.entity.output", "langsmith.inputs", "langsmith.outputs",
+           "http.request.body", "http.response.body", "db.query.text", "db.statement", "messaging.message.body",
+           "exception.stacktrace", "code.stacktrace")
+_state: dict = {}
+
+
+class _MetadataOnly(SpanExporter):
+    """Removes content attributes (and content in events) before spans leave the process."""
+
+    def __init__(self, inner: SpanExporter):
+        self.inner = inner
+
+    def export(self, spans):
+        return self.inner.export([_without_content(span) for span in spans])
+
+    def shutdown(self):
+        return self.inner.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000):
+        return self.inner.force_flush(timeout_millis)
+
+
+def _metadata(attributes) -> dict:
+    return {k: v for k, v in (attributes or {}).items() if not k.startswith(CONTENT)}
+
+
+def _without_content(span: ReadableSpan) -> ReadableSpan:
+    """A copy of a finished span without content attributes (a finished span cannot be changed in place)."""
+    if not any(k.startswith(CONTENT) for k in span.attributes or {}) and not any(
+            k.startswith(CONTENT) for e in span.events for k in e.attributes or {}):
+        return span
+    return ReadableSpan(
+        name=span.name, context=span.context, parent=span.parent, resource=span.resource,
+        attributes=_metadata(span.attributes),
+        events=[Event(e.name, _metadata(e.attributes), e.timestamp) for e in span.events], links=span.links,
+        kind=span.kind, status=span.status, start_time=span.start_time, end_time=span.end_time,
+        instrumentation_scope=span.instrumentation_scope)
+
+
+def _revision() -> str | None:
+    return next((os.environ[v] for v in REVISION_VARIABLES if os.environ.get(v)), None)
+
+
+def init(key: str | None = None, service: str | None = None, version: str | None = None, revision: str | None = None,
+         endpoint: str | None = None, capture_content: bool = False) -> TracerProvider:
+    """Start sending traces. Returns the tracer provider spans go through (yours, when you already had one)."""
+    from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+    key = key or os.environ.get("WEHARNESS_INGEST_KEY")
+    if not key:
+        raise ValueError("Give the project's ingest key: init(key=...) or WEHARNESS_INGEST_KEY.")
+    exporter: SpanExporter = OTLPSpanExporter(endpoint=endpoint or os.environ.get("WEHARNESS_OTLP_ENDPOINT") or ENDPOINT,
+                                              headers={"Authorization": f"Bearer {key}"}, timeout=10)
+    if not capture_content:
+        exporter = _MetadataOnly(exporter)
+    processor = BatchSpanProcessor(exporter, max_queue_size=2048, max_export_batch_size=512, schedule_delay_millis=2000)
+    current = trace.get_tracer_provider()
+    if isinstance(current, TracerProvider):  # coexist with the application's own OpenTelemetry setup
+        provider = current
+    else:
+        attributes = {"service.name": service or os.environ.get("OTEL_SERVICE_NAME") or "unknown_service"}
+        if version:
+            attributes["service.version"] = version
+        if revision or _revision():
+            attributes["vcs.ref.head.revision"] = revision or _revision()
+        provider = TracerProvider(resource=Resource.create(attributes))
+        trace.set_tracer_provider(provider)
+    provider.add_span_processor(processor)
+    _state.update(provider=provider, processor=processor, tracer=provider.get_tracer("weharness-tracing", __version__))
+    return provider
+
+
+def _tracer():
+    return _state.get("tracer") or trace.get_tracer("weharness-tracing", __version__)
+
+
+class _Span:
+    def __init__(self, span):
+        self.span = span
+
+    def usage(self, input_tokens: int | None = None, output_tokens: int | None = None) -> None:
+        if input_tokens is not None:
+            self.span.set_attribute("gen_ai.usage.input_tokens", int(input_tokens))
+        if output_tokens is not None:
+            self.span.set_attribute("gen_ai.usage.output_tokens", int(output_tokens))
+
+    def set(self, key: str, value) -> None:
+        self.span.set_attribute(key, value)
+
+
+@contextmanager
+def agent_run(name: str, **attributes):
+    """One run of your agent: the root of a trace (`invoke_agent`)."""
+    with _tracer().start_as_current_span(f"invoke_agent {name}", attributes={
+            "gen_ai.operation.name": "invoke_agent", "gen_ai.agent.name": name, **attributes}) as span:
+        yield _Span(span)
+
+
+@contextmanager
+def model_call(model: str, provider: str | None = None, operation: str = "chat", **attributes):
+    """A call to a model (`chat`), with its token usage."""
+    extra = {"gen_ai.provider.name": provider} if provider else {}
+    with _tracer().start_as_current_span(f"{operation} {model}", kind=trace.SpanKind.CLIENT, attributes={
+            "gen_ai.operation.name": operation, "gen_ai.request.model": model, **extra, **attributes}) as span:
+        yield _Span(span)
+
+
+def _caller() -> dict:
+    """Where the application called a helper: its file (relative to the working directory, which is the repository
+    when the application runs from its root), line and function, so WeHarness can open the code a tool call ran.
+    A caller outside the working directory gives its function only."""
+    frame = sys._getframe(1)
+    while frame is not None and (frame.f_code.co_filename == __file__ or frame.f_code.co_filename.endswith("contextlib.py")):
+        frame = frame.f_back
+    if frame is None:
+        return {}
+    where = {"code.function.name": frame.f_code.co_name}
+    try:
+        path = os.path.relpath(frame.f_code.co_filename)
+    except ValueError:  # another drive (Windows)
+        return where
+    if path.startswith("..") or os.path.isabs(path) or "site-packages" in path:
+        return where
+    return {**where, "code.file.path": path.replace(os.sep, "/"), "code.line.number": frame.f_lineno}
+
+
+@contextmanager
+def tool_call(name: str, call_id: str | None = None, **attributes):
+    """A tool your agent calls (`execute_tool`), with where in your code it was called (code.*)."""
+    extra = {"gen_ai.tool.call.id": call_id, **_caller()} if call_id else _caller()
+    with _tracer().start_as_current_span(f"execute_tool {name}", attributes={
+            "gen_ai.operation.name": "execute_tool", "gen_ai.tool.name": name, **extra, **attributes}) as span:
+        yield _Span(span)
+
+
+def shutdown(timeout_millis: int = 10000) -> None:
+    """Send what is still queued (call before the process exits)."""
+    processor = _state.get("processor")
+    if processor is not None:
+        processor.force_flush(timeout_millis)