Add SuperCompress integration example + docs

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"

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
+
+<CodeGroup>
+```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
+```
+</CodeGroup>
+
+## 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.
+
+<CodeGroup>
+```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"
+```
+</CodeGroup>
+
+## 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)

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

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

examples/supercompress/requirements.txt

@@ -0,0 +1,4 @@
+agentops
+openai
+supercompress
+python-dotenv

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"
+   ]
+  }
+ ]
+}

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()