From b86d4904f926a0e867dac3a42035929a34fdd6da Mon Sep 17 00:00:00 2001 From: arjunkshah21 Date: Sat, 3 Oct 2026 08:50:51 -0700 Subject: [PATCH] Add SuperCompress integration example and docs Show query-aware context compression before LLM calls with AgentOps tracing so token/cost savings show up in the dashboard. Co-authored-by: Cursor --- docs/mint.json | 1 + docs/v2/integrations/supercompress.mdx | 108 ++++++++++++++++++ examples/README.md | 4 + examples/supercompress/README.md | 21 ++++ examples/supercompress/requirements.txt | 4 + .../supercompress/supercompress_example.ipynb | 104 +++++++++++++++++ .../supercompress/supercompress_example.py | 96 ++++++++++++++++ 7 files changed, 338 insertions(+) create mode 100644 docs/v2/integrations/supercompress.mdx create mode 100644 examples/supercompress/README.md create mode 100644 examples/supercompress/requirements.txt create mode 100644 examples/supercompress/supercompress_example.ipynb create mode 100644 examples/supercompress/supercompress_example.py diff --git a/docs/mint.json b/docs/mint.json index bab8c9134..64d1c6fd9 100644 --- a/docs/mint.json +++ b/docs/mint.json @@ -157,6 +157,7 @@ "v2/integrations/openai_agents_python", "v2/integrations/openai_agents_js", "v2/integrations/smolagents", + "v2/integrations/supercompress", "v2/integrations/ibm_watsonx_ai", "v2/integrations/xai", "v2/integrations/xpander" diff --git a/docs/v2/integrations/supercompress.mdx b/docs/v2/integrations/supercompress.mdx new file mode 100644 index 000000000..02327fd56 --- /dev/null +++ b/docs/v2/integrations/supercompress.mdx @@ -0,0 +1,108 @@ +--- +title: SuperCompress +description: "Compress bulky agent context before LLM calls and track the token/cost impact with AgentOps" +--- + +[SuperCompress](https://www.supercompress.dev) is query-aware context compression for LLM agents. +It shrinks noisy tool dumps and history **before** the model call while keeping the user ask intact. +AgentOps then traces the resulting LLM spend so you can see dollars avoided in the dashboard. + +## Why SuperCompress + AgentOps? + +| Concern | SuperCompress | AgentOps | +| ------- | ------------- | -------- | +| Cut tokens in bulky context | ✅ | — | +| Keep the latest user ask untouched | ✅ | — | +| Replay / debug agent runs | — | ✅ | +| Track LLM cost across providers | — | ✅ | + +Typical agent flows pay for huge system/tool payloads. Compress first, then let AgentOps show the cheaper completion. + +## Installation + + +```bash pip +pip install agentops supercompress openai python-dotenv +``` +```bash poetry +poetry add agentops supercompress openai python-dotenv +``` +```bash uv +uv pip install agentops supercompress openai python-dotenv +``` + + +## API keys + +- **AGENTOPS_API_KEY** — [AgentOps dashboard](https://app.agentops.ai/settings/projects) +- **OPENAI_API_KEY** — (or any OpenAI-compatible provider you call after compress) +- **SUPERCOMPRESS_API_KEY** — optional; required only for hosted `mode="precision"` / Neural Keep. Local `mode="compiler"` works without it. + + +```bash Export to CLI +export AGENTOPS_API_KEY="your_agentops_api_key_here" +export OPENAI_API_KEY="your_openai_api_key_here" +# optional hosted SuperCompress +export SUPERCOMPRESS_API_KEY="your_supercompress_api_key_here" +``` +```txt Set in .env file +AGENTOPS_API_KEY="your_agentops_api_key_here" +OPENAI_API_KEY="your_openai_api_key_here" +SUPERCOMPRESS_API_KEY="your_supercompress_api_key_here" +``` + + +## Usage + +```python +import os +from dotenv import load_dotenv + +load_dotenv() + +import agentops +from openai import OpenAI +from supercompress import compress_for_turn + +agentops.init(auto_start_session=False, trace_name="SuperCompress Example") +tracer = agentops.start_trace( + trace_name="SuperCompress Example", + tags=["supercompress", "token-savings"], +) + +bulky_context = "... long tool dump / history ..." +user_ask = "Why does checkout crash on empty cart?" + +# Never put the ask into the compression target as the only input — +# pass it as user_query so SuperCompress keeps it intact. +result = compress_for_turn( + context="", + user_query=user_ask, + context_blocks=[bulky_context], + budget_ratio=0.35, + mode="compiler", # or "precision" with SUPERCOMPRESS_API_KEY +) + +client = OpenAI() +response = client.chat.completions.create( + model="gpt-4o-mini", + messages=[ + {"role": "system", "content": result.compressed_text}, + {"role": "user", "content": user_ask}, + ], +) +print(response.choices[0].message.content) +print(f"tokens {result.original_tokens} → {result.kept_tokens}") + +agentops.end_trace(tracer, end_state="Success") +``` + +## Example notebook + +See [`examples/supercompress/`](https://github.com/AgentOps-AI/agentops/tree/main/examples/supercompress) for a runnable script + notebook. + +## Links + +- [SuperCompress](https://www.supercompress.dev) +- [SuperCompress docs](https://www.supercompress.dev/docs/integrations) +- [AgentOps dashboard](https://app.agentops.ai) diff --git a/examples/README.md b/examples/README.md index 93a6ccfb0..bc7d4e11a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -61,6 +61,10 @@ This directory contains comprehensive examples demonstrating how to integrate Ag - `grok_examples` - Basic Grok API usage - `grok_vision_examples` - Vision capabilities with Grok + +- **[`supercompress/`](./supercompress/)** - Query-aware context compression before LLM calls + - `supercompress_example` - Compress bulky agent dumps, keep the ask, track savings in AgentOps + ### Utility Scripts - **[`generate_documentation.py`](./generate_documentation.py)** - Script to convert Jupyter notebooks to MDX documentation files diff --git a/examples/supercompress/README.md b/examples/supercompress/README.md new file mode 100644 index 000000000..9d785c856 --- /dev/null +++ b/examples/supercompress/README.md @@ -0,0 +1,21 @@ +# SuperCompress + AgentOps + +Query-aware context compression before LLM calls, with AgentOps cost/token tracing. + +## Setup + +```bash +pip install -r requirements.txt +export AGENTOPS_API_KEY=... +export OPENAI_API_KEY=... +# optional hosted path +export SUPERCOMPRESS_API_KEY=... +``` + +## Run + +```bash +python supercompress_example.py +``` + +Docs: https://www.supercompress.dev · https://docs.agentops.ai diff --git a/examples/supercompress/requirements.txt b/examples/supercompress/requirements.txt new file mode 100644 index 000000000..86c43e0dd --- /dev/null +++ b/examples/supercompress/requirements.txt @@ -0,0 +1,4 @@ +agentops +openai +supercompress +python-dotenv diff --git a/examples/supercompress/supercompress_example.ipynb b/examples/supercompress/supercompress_example.ipynb new file mode 100644 index 000000000..1c7e7fda3 --- /dev/null +++ b/examples/supercompress/supercompress_example.ipynb @@ -0,0 +1,104 @@ +{ + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# SuperCompress + AgentOps\n", + "\n", + "Compress bulky agent context before the LLM call, then observe token/cost impact in AgentOps.\n", + "\n", + "- [SuperCompress](https://www.supercompress.dev)\n", + "- [AgentOps](https://agentops.ai)\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "%pip install -U agentops supercompress openai python-dotenv\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "import os\n", + "from dotenv import load_dotenv\n", + "\n", + "load_dotenv()\n", + "\n", + "os.environ[\"AGENTOPS_API_KEY\"] = os.getenv(\"AGENTOPS_API_KEY\", \"your_api_key_here\")\n", + "os.environ[\"OPENAI_API_KEY\"] = os.getenv(\"OPENAI_API_KEY\", \"your_openai_api_key_here\")\n", + "os.environ.setdefault(\"SUPERCOMPRESS_API_KEY\", os.getenv(\"SUPERCOMPRESS_API_KEY\", \"\"))\n", + "\n", + "import agentops\n", + "from openai import OpenAI\n", + "from supercompress import compress_for_turn\n" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "BULKY_CONTEXT = \"\"\"\n", + "Root cause: null deref in checkout when cart.line_items is empty.\n", + "Fix hint: guard cart.line_items before mapping SKUs.\n", + "Passed unit tests for shipping calculator.\n", + "Noise: redis reconnect logs repeating 40 times.\n", + "Noise: webpack rebuild spam.\n", + "GraphQL schema noise...\n", + "\"\"\"\n", + "USER_ASK = \"Why does checkout crash on empty cart?\"\n", + "\n", + "agentops.init(auto_start_session=False, trace_name=\"SuperCompress Example\")\n", + "tracer = agentops.start_trace(\n", + " trace_name=\"SuperCompress Example\",\n", + " tags=[\"supercompress-example\", \"agentops-example\", \"token-savings\"],\n", + ")\n", + "\n", + "result = compress_for_turn(\n", + " context=\"\",\n", + " user_query=USER_ASK,\n", + " context_blocks=[BULKY_CONTEXT],\n", + " budget_ratio=0.35,\n", + " mode=\"compiler\",\n", + ")\n", + "print(f\"{result.original_tokens} \u2192 {result.kept_tokens} tokens ({result.tokens_saved_pct}% saved)\")\n", + "\n", + "client = OpenAI()\n", + "response = client.chat.completions.create(\n", + " model=\"gpt-4o-mini\",\n", + " messages=[\n", + " {\"role\": \"system\", \"content\": result.compressed_text},\n", + " {\"role\": \"user\", \"content\": USER_ASK},\n", + " ],\n", + ")\n", + "print(response.choices[0].message.content)\n", + "\n", + "agentops.end_trace(tracer, end_state=\"Success\")\n", + "agentops.validate_trace_spans(trace_context=tracer)\n", + "print(\"\u2705 AgentOps spans OK\")\n" + ] + } + ] +} \ No newline at end of file diff --git a/examples/supercompress/supercompress_example.py b/examples/supercompress/supercompress_example.py new file mode 100644 index 000000000..ecc9f26a2 --- /dev/null +++ b/examples/supercompress/supercompress_example.py @@ -0,0 +1,96 @@ +""" +# SuperCompress + AgentOps + +Compress bulky agent context before the LLM call, then observe token/cost impact in AgentOps. + +[SuperCompress](https://www.supercompress.dev) is query-aware context compression. +[AgentOps](https://agentops.ai) traces LLM spend and agent runs. + +Pattern: bulky context → SuperCompress (keep ask intact) → OpenAI → AgentOps spans. +""" + +import os +from dotenv import load_dotenv + +load_dotenv() + +# Next, we'll set our API keys. There are several ways to do this; this covers +# both env-file users and notebook paste. Remember not to commit real keys. +# +# [Get an AgentOps API key](https://app.agentops.ai/settings/projects) +# [Get a SuperCompress API key](https://www.supercompress.dev/dashboard) (optional for local compiler mode) + +os.environ["AGENTOPS_API_KEY"] = os.getenv("AGENTOPS_API_KEY", "your_api_key_here") +os.environ["OPENAI_API_KEY"] = os.getenv("OPENAI_API_KEY", "your_openai_api_key_here") +os.environ.setdefault("SUPERCOMPRESS_API_KEY", os.getenv("SUPERCOMPRESS_API_KEY", "")) + +import agentops +from openai import OpenAI +from supercompress import compress_for_turn + +BULKY_CONTEXT = """ +# Agent dump (synthetic) + +Root cause: null deref in checkout when cart.line_items is empty. +Fix hint: guard cart.line_items before mapping SKUs. +Passed unit tests for shipping calculator. +Unrelated filler about yesterday's standup and coffee preferences. +Noise: redis reconnect logs repeating 40 times. +Noise: webpack rebuild spam. +Noise: deprecated warning stack from leftover middleware. +GraphQL schema for ProductVariant is 800 lines of noise here. +Protobuf definitions for InventoryService (truncated). +Deno deploy logs from an unrelated service. +RFC8259 JSON grammar excerpts nobody asked for. +esbuild timing tables. +CRDT merge notes for a different ticket. +Wasm trap tables. +""" + +USER_ASK = "Why does checkout crash on empty cart?" + + +def main(): + agentops.init(auto_start_session=False, trace_name="SuperCompress Example") + tracer = agentops.start_trace( + trace_name="SuperCompress Example", + tags=["supercompress-example", "agentops-example", "token-savings"], + ) + + # Compress bulky context; never compress the user ask itself. + result = compress_for_turn( + context="", + user_query=USER_ASK, + context_blocks=[BULKY_CONTEXT], + budget_ratio=0.35, + # "compiler" = local query-aware fallback (no hosted key required). + # Use mode="precision" + SUPERCOMPRESS_API_KEY for the hosted Neural Keep path. + mode="compiler", + ) + print( + f"SuperCompress: {result.original_tokens} → {result.kept_tokens} tokens " + f"({result.tokens_saved_pct}% saved, mode={result.mode})" + ) + + client = OpenAI() + messages = [ + {"role": "system", "content": result.compressed_text}, + {"role": "user", "content": USER_ASK}, + ] + response = client.chat.completions.create(model="gpt-4o-mini", messages=messages) + print(response.choices[0].message.content) + + agentops.end_trace(tracer, end_state="Success") + + print("\n" + "=" * 50) + print("Verifying AgentOps spans...") + try: + agentops.validate_trace_spans(trace_context=tracer) + print("\n✅ Success! LLM spans recorded in AgentOps.") + except agentops.ValidationError as e: + print(f"\n❌ Error validating spans: {e}") + raise + + +if __name__ == "__main__": + main()