metergraphrelay 0.1.0__tar.gz

metergraphrelay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vasiliy Radostev
+
+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.

metergraphrelay-0.1.0/PKG-INFO

@@ -0,0 +1,144 @@
+Metadata-Version: 2.4
+Name: metergraphrelay
+Version: 0.1.0
+Summary: Move LLM trace data between systems: pull from providers, push to metergraph.
+Author: Vasiliy Radostev
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/VasiliyRad/metergraphrelay
+Project-URL: Repository, https://github.com/VasiliyRad/metergraphrelay
+Project-URL: Issues, https://github.com/VasiliyRad/metergraphrelay/issues
+Keywords: llm,openai,observability,cost-tracking,cli,metergraph
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Environment :: Console
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: openai>=1.63.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# metergraphrelay
+
+Export OpenAI stored chat completions as trace records, and optionally
+generate demo conversations to try it out.
+
+## Purpose
+
+Download the chat completions already stored in *your own* OpenAI
+account (completions created with `store=True`) as local JSONL trace
+records — useful for auditing, backups, or feeding into other tooling.
+This tool only reads what's associated with the API key you provide; it
+can't see or export anyone else's data.
+
+Built on OpenAI's [List Chat Completions API](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list),
+which returns completions that were created with `store: true`. See the
+[official OpenAI API reference](https://developers.openai.com/api/reference/chat-completions/overview)
+for the underlying data model.
+
+## Setup
+
+    pip install -e ".[dev]"
+    cp .env.example .env
+    # edit .env and set OPENAI_API_KEY
+
+## Usage
+
+Generate 1-2 demo conversations (stored with `store=True`) so there's
+data to pull:
+
+    metergraphrelay demo openai
+
+Pull the 10 most recent stored chat completions into `traces.jsonl`,
+already shaped as metergraph trace records:
+
+    metergraphrelay pull openai
+
+Options:
+
+    metergraphrelay pull openai -n 25 --output my-traces.jsonl --stdout --include-content --route my-app/support-bot
+    metergraphrelay demo openai --model gpt-4o-mini
+
+Push a local JSONL file of traces to metergraph:
+
+    metergraphrelay push traces.jsonl
+
+`pull anthropic` and `pull langfuse` accept the same shape but are not
+yet implemented in this version — they check for `ANTHROPIC_API_KEY` /
+`LANGFUSE_PUBLIC_KEY`+`LANGFUSE_SECRET_KEY` and report accordingly.
+
+All subcommands accept `--env-file PATH` to point at a config file
+other than `./.env`.
+
+## Using it against your real system (not just the demo)
+
+`metergraphrelay pull openai` only finds completions that were created
+with `store=True`. The `demo openai` subcommand sets that flag for you,
+but for your own application to show up in a pull, its own OpenAI calls
+need the same flag. The only change required is adding `store=True`
+(and, optionally, `metadata` to help you tell requests apart later) to
+calls you're already making:
+
+    from openai import OpenAI
+
+    client = OpenAI()
+
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "..."}],
+        store=True,                       # <-- persists this completion for later pulling
+        metadata={"source": "my-app"},    # optional: filter/identify later via the API
+    )
+
+No other code changes are needed — the request and response are handled
+exactly as before. Once your app is sending `store=True`, its completions
+become visible to `metergraphrelay pull openai` (or to the
+[List Chat Completions API](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list)
+directly) using the same API key.
+
+Two things worth knowing before flipping this on in production:
+- Stored completions include full request/response content by default,
+  so treat them as you would any other place your data is retained.
+- Storage has no automatic expiry from this tool's side — deletion is a
+  separate API call ([Delete chat completion](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/delete)),
+  not something `metergraphrelay` currently does.
+
+## Trace record shape
+
+Each line of `pull openai`'s output is a JSON object already shaped for
+metergraph's ingest API:
+
+    {
+      "ts": "2026-07-30T12:00:00+00:00",
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "status": "success",
+      "endpoint": "chat.completions",
+      "input_tokens": 12,
+      "output_tokens": 34,
+      "error": false,
+      "error_type": null,
+      "request_id": "chatcmpl-...",
+      "tags": {},
+      "route": "openai/backfill",
+      "content_opted_in": false,
+      "request_json": null,
+      "response_text": null,
+      "sdk": "metergraphrelay",
+      "sdk_version": "0.1.0"
+    }
+
+`request_json`/`response_text` are populated only when `--include-content`
+is passed.
+
+Every completion returned by the stored-completions list already succeeded, so
+`status` is always `"success"`. `error`/`error_type` flag a *partial* record:
+`--include-content` was requested but the follow-up message fetch failed, so
+token counts are still real while the content is missing.
+
+## Running tests
+
+    pytest

metergraphrelay-0.1.0/README.md

@@ -0,0 +1,121 @@
+# metergraphrelay
+
+Export OpenAI stored chat completions as trace records, and optionally
+generate demo conversations to try it out.
+
+## Purpose
+
+Download the chat completions already stored in *your own* OpenAI
+account (completions created with `store=True`) as local JSONL trace
+records — useful for auditing, backups, or feeding into other tooling.
+This tool only reads what's associated with the API key you provide; it
+can't see or export anyone else's data.
+
+Built on OpenAI's [List Chat Completions API](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list),
+which returns completions that were created with `store: true`. See the
+[official OpenAI API reference](https://developers.openai.com/api/reference/chat-completions/overview)
+for the underlying data model.
+
+## Setup
+
+    pip install -e ".[dev]"
+    cp .env.example .env
+    # edit .env and set OPENAI_API_KEY
+
+## Usage
+
+Generate 1-2 demo conversations (stored with `store=True`) so there's
+data to pull:
+
+    metergraphrelay demo openai
+
+Pull the 10 most recent stored chat completions into `traces.jsonl`,
+already shaped as metergraph trace records:
+
+    metergraphrelay pull openai
+
+Options:
+
+    metergraphrelay pull openai -n 25 --output my-traces.jsonl --stdout --include-content --route my-app/support-bot
+    metergraphrelay demo openai --model gpt-4o-mini
+
+Push a local JSONL file of traces to metergraph:
+
+    metergraphrelay push traces.jsonl
+
+`pull anthropic` and `pull langfuse` accept the same shape but are not
+yet implemented in this version — they check for `ANTHROPIC_API_KEY` /
+`LANGFUSE_PUBLIC_KEY`+`LANGFUSE_SECRET_KEY` and report accordingly.
+
+All subcommands accept `--env-file PATH` to point at a config file
+other than `./.env`.
+
+## Using it against your real system (not just the demo)
+
+`metergraphrelay pull openai` only finds completions that were created
+with `store=True`. The `demo openai` subcommand sets that flag for you,
+but for your own application to show up in a pull, its own OpenAI calls
+need the same flag. The only change required is adding `store=True`
+(and, optionally, `metadata` to help you tell requests apart later) to
+calls you're already making:
+
+    from openai import OpenAI
+
+    client = OpenAI()
+
+    response = client.chat.completions.create(
+        model="gpt-4o-mini",
+        messages=[{"role": "user", "content": "..."}],
+        store=True,                       # <-- persists this completion for later pulling
+        metadata={"source": "my-app"},    # optional: filter/identify later via the API
+    )
+
+No other code changes are needed — the request and response are handled
+exactly as before. Once your app is sending `store=True`, its completions
+become visible to `metergraphrelay pull openai` (or to the
+[List Chat Completions API](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/list)
+directly) using the same API key.
+
+Two things worth knowing before flipping this on in production:
+- Stored completions include full request/response content by default,
+  so treat them as you would any other place your data is retained.
+- Storage has no automatic expiry from this tool's side — deletion is a
+  separate API call ([Delete chat completion](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/delete)),
+  not something `metergraphrelay` currently does.
+
+## Trace record shape
+
+Each line of `pull openai`'s output is a JSON object already shaped for
+metergraph's ingest API:
+
+    {
+      "ts": "2026-07-30T12:00:00+00:00",
+      "provider": "openai",
+      "model": "gpt-4o-mini",
+      "status": "success",
+      "endpoint": "chat.completions",
+      "input_tokens": 12,
+      "output_tokens": 34,
+      "error": false,
+      "error_type": null,
+      "request_id": "chatcmpl-...",
+      "tags": {},
+      "route": "openai/backfill",
+      "content_opted_in": false,
+      "request_json": null,
+      "response_text": null,
+      "sdk": "metergraphrelay",
+      "sdk_version": "0.1.0"
+    }
+
+`request_json`/`response_text` are populated only when `--include-content`
+is passed.
+
+Every completion returned by the stored-completions list already succeeded, so
+`status` is always `"success"`. `error`/`error_type` flag a *partial* record:
+`--include-content` was requested but the follow-up message fetch failed, so
+token counts are still real while the content is missing.
+
+## Running tests
+
+    pytest

metergraphrelay-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "metergraphrelay"
+version = "0.1.0"
+description = "Move LLM trace data between systems: pull from providers, push to metergraph."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Vasiliy Radostev" }]
+keywords = ["llm", "openai", "observability", "cost-tracking", "cli", "metergraph"]
+classifiers = [
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Environment :: Console",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openai>=1.63.0",
+    "python-dotenv>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/VasiliyRad/metergraphrelay"
+Repository = "https://github.com/VasiliyRad/metergraphrelay"
+Issues = "https://github.com/VasiliyRad/metergraphrelay/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8.0"]
+
+[project.scripts]
+metergraphrelay = "metergraphrelay.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

metergraphrelay-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

metergraphrelay-0.1.0/src/metergraphrelay/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

metergraphrelay-0.1.0/src/metergraphrelay/cli.py

@@ -0,0 +1,141 @@
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+from openai import OpenAI
+
+from .config import ConfigError, require_credentials
+from .demo import run_demo
+from .providers.openai import pull_openai
+from .push import push_file
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="metergraphrelay")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    pull_parser = subparsers.add_parser(
+        "pull", help="Pull trace data from a provider into a local JSONL file"
+    )
+    pull_subparsers = pull_parser.add_subparsers(dest="provider", required=True)
+
+    pull_openai_parser = pull_subparsers.add_parser("openai")
+    pull_openai_parser.add_argument("-n", "--count", type=int, default=10)
+    pull_openai_parser.add_argument("--output", default="traces.jsonl")
+    pull_openai_parser.add_argument("--stdout", action="store_true")
+    pull_openai_parser.add_argument("--route", default="openai/backfill")
+    pull_openai_parser.add_argument("--include-content", action="store_true")
+    pull_openai_parser.add_argument("--env-file", default=".env")
+
+    pull_anthropic_parser = pull_subparsers.add_parser("anthropic")
+    pull_anthropic_parser.add_argument("-n", "--count", type=int, default=10)
+    pull_anthropic_parser.add_argument("--output", default="traces.jsonl")
+    pull_anthropic_parser.add_argument("--env-file", default=".env")
+
+    pull_langfuse_parser = pull_subparsers.add_parser("langfuse")
+    pull_langfuse_parser.add_argument("--output", default="traces.jsonl")
+    pull_langfuse_parser.add_argument("--env-file", default=".env")
+
+    demo_parser = subparsers.add_parser(
+        "demo", help="Run 1-2 demo conversations with store=True"
+    )
+    demo_subparsers = demo_parser.add_subparsers(dest="provider", required=True)
+    demo_openai_parser = demo_subparsers.add_parser("openai")
+    demo_openai_parser.add_argument("--model", default="gpt-4o-mini")
+    demo_openai_parser.add_argument("--env-file", default=".env")
+
+    push_parser = subparsers.add_parser(
+        "push", help="Push a local JSONL file of traces to metergraph"
+    )
+    push_parser.add_argument("file")
+    push_parser.add_argument("--env-file", default=".env")
+
+    return parser
+
+
+def _config_error(exc: ConfigError) -> int:
+    print(f"Error: {exc}", file=sys.stderr)
+    return 1
+
+
+def _os_error(exc: OSError) -> int:
+    print(f"Error: {exc}", file=sys.stderr)
+    return 1
+
+
+def _not_implemented(provider: str) -> int:
+    print(
+        f"Error: pulling from {provider} is not implemented in this version.",
+        file=sys.stderr,
+    )
+    return 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "pull" and args.provider in {"anthropic", "langfuse"}:
+        try:
+            require_credentials(args.provider, args.env_file)
+        except ConfigError as exc:
+            return _config_error(exc)
+        return _not_implemented(args.provider)
+
+    if args.command == "pull" and args.provider == "openai":
+        try:
+            creds = require_credentials("openai", args.env_file)
+        except ConfigError as exc:
+            return _config_error(exc)
+        client = OpenAI(api_key=creds["OPENAI_API_KEY"])
+        try:
+            written = pull_openai(
+                client,
+                args.count,
+                args.output,
+                route=args.route,
+                include_content=args.include_content,
+                echo_stdout=args.stdout,
+            )
+        except OSError as exc:
+            return _os_error(exc)
+        if written == 0:
+            print("No stored completions found. Try `metergraphrelay demo openai` first.")
+        else:
+            print(f"Wrote {written} trace(s) to {args.output}")
+        return 0
+
+    if args.command == "demo" and args.provider == "openai":
+        try:
+            creds = require_credentials("openai", args.env_file)
+        except ConfigError as exc:
+            return _config_error(exc)
+        client = OpenAI(api_key=creds["OPENAI_API_KEY"])
+        run_demo(client, model=args.model)
+        return 0
+
+    if args.command == "push":
+        try:
+            creds = require_credentials("push", args.env_file)
+        except ConfigError as exc:
+            return _config_error(exc)
+        base_url = os.environ.get("METERGRAPH_INGEST_URL")
+        try:
+            succeeded, failed = push_file(
+                args.file, creds["METERGRAPH_APP_TOKEN"], base_url=base_url
+            )
+        except OSError as exc:
+            return _os_error(exc)
+        if failed:
+            print(f"Pushed {succeeded} row(s), {failed} failed.", file=sys.stderr)
+            return 1
+        print(f"Pushed {succeeded} row(s) to metergraph.")
+        return 0
+
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

metergraphrelay-0.1.0/src/metergraphrelay/config.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+
+from dotenv import load_dotenv
+
+
+class ConfigError(Exception):
+    """Raised when required configuration is missing or invalid."""
+
+
+CREDENTIAL_SPECS: dict[str, list[str]] = {
+    "openai": ["OPENAI_API_KEY"],
+    "anthropic": ["ANTHROPIC_API_KEY"],
+    "langfuse": ["LANGFUSE_PUBLIC_KEY", "LANGFUSE_SECRET_KEY"],
+    "push": ["METERGRAPH_APP_TOKEN"],
+}
+
+
+def require_credentials(target: str, env_file: str = ".env") -> dict[str, str]:
+    load_dotenv(env_file, override=True)
+    var_names = CREDENTIAL_SPECS[target]
+    values: dict[str, str] = {}
+    missing: list[str] = []
+    for name in var_names:
+        value = os.environ.get(name, "").strip()
+        if value:
+            values[name] = value
+        else:
+            missing.append(name)
+    if missing:
+        joined = ", ".join(missing)
+        raise ConfigError(
+            f"{joined} not set. Add {'it' if len(missing) == 1 else 'them'} to "
+            f"{env_file} (see .env.example) or export in your shell."
+        )
+    return values

metergraphrelay-0.1.0/src/metergraphrelay/demo.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from typing import Any
+
+DEMO_PROMPTS = [
+    "Say hello in one sentence.",
+    "What's 2+2?",
+]
+
+
+def run_demo(client: Any, *, model: str = "gpt-4o-mini") -> list[dict]:
+    results = []
+    for prompt in DEMO_PROMPTS:
+        completion = client.chat.completions.create(
+            model=model,
+            store=True,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        reply = completion.choices[0].message.content
+        print(f"> {prompt}\n{reply}\n")
+        results.append({"prompt": prompt, "reply": reply})
+    return results

metergraphrelay-0.1.0/src/metergraphrelay/providers/openai.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+
+import json
+import sys
+from datetime import datetime, timezone
+from itertools import islice
+from typing import Any, Iterable
+
+from .. import __version__
+
+
+def normalize_completion(
+    completion: Any,
+    messages: Iterable[Any],
+    *,
+    route: str,
+    include_content: bool,
+    content_fetch_error: Exception | None = None,
+) -> dict:
+    usage = getattr(completion, "usage", None)
+    tags = getattr(completion, "metadata", None) or {}
+    ts = datetime.fromtimestamp(completion.created, tz=timezone.utc).isoformat()
+    message_list = list(messages)
+
+    content_opted_in = include_content and content_fetch_error is None
+    request_json: str | None = None
+    response_text: str | None = None
+    if content_opted_in:
+        if message_list and message_list[-1].role == "assistant":
+            response_text = message_list[-1].content
+            request_messages = message_list[:-1]
+        else:
+            request_messages = message_list
+        request_json = json.dumps(
+            [{"role": m.role, "content": m.content} for m in request_messages]
+        )
+
+    return {
+        "ts": ts,
+        "provider": "openai",
+        "model": completion.model,
+        "status": "success",
+        "endpoint": "chat.completions",
+        "input_tokens": getattr(usage, "prompt_tokens", None) if usage else None,
+        "output_tokens": getattr(usage, "completion_tokens", None) if usage else None,
+        "error": content_fetch_error is not None,
+        "error_type": (
+            type(content_fetch_error).__name__ if content_fetch_error else None
+        ),
+        "request_id": completion.id,
+        "tags": tags,
+        "route": route,
+        "content_opted_in": content_opted_in,
+        "request_json": request_json,
+        "response_text": response_text,
+        "sdk": "metergraphrelay",
+        "sdk_version": __version__,
+    }
+
+
+def pull_openai(
+    client: Any,
+    count: int,
+    output_path: str,
+    *,
+    route: str,
+    include_content: bool,
+    echo_stdout: bool = False,
+) -> int:
+    page = client.chat.completions.list(order="desc", limit=count)
+    completions = list(islice(iter(page), count))
+    written = 0
+    with open(output_path, "w") as f:
+        for completion in completions:
+            if not include_content:
+                row = normalize_completion(
+                    completion, [], route=route, include_content=include_content
+                )
+            else:
+                try:
+                    messages = client.chat.completions.messages.list(completion.id)
+                except Exception as exc:
+                    print(
+                        f"Warning: could not fetch messages for {completion.id}: {exc}",
+                        file=sys.stderr,
+                    )
+                    row = normalize_completion(
+                        completion, [], route=route, include_content=include_content,
+                        content_fetch_error=exc,
+                    )
+                else:
+                    row = normalize_completion(
+                        completion, messages, route=route,
+                        include_content=include_content,
+                    )
+            line = json.dumps(row)
+            f.write(line + "\n")
+            if echo_stdout:
+                print(line)
+            written += 1
+    return written