starnose 0.1.0__tar.gz

starnose-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,65 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  update-homebrew:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Get version
+        id: version
+        run: echo "version=${GITHUB_REF#refs/tags/v}" >> $GITHUB_OUTPUT
+
+      - name: Trigger Homebrew tap update
+        run: |
+          echo "Update your Homebrew formula with:"
+          echo "  version: ${{ steps.version.outputs.version }}"
+          echo "  url: https://pypi.org/packages/source/s/starnose/starnose-${{ steps.version.outputs.version }}.tar.gz"
+          echo ""
+          echo "Run: scripts/update-homebrew.sh ${{ steps.version.outputs.version }}"

starnose-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,31 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]" 2>/dev/null || pip install -e .
+
+      - name: Install test dependencies
+        run: pip install pytest
+
+      - name: Run tests
+        run: python -m pytest tests/ -v

starnose-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+*.db
+.starnose/

starnose-0.1.0/Formula/starnose.rb

@@ -0,0 +1,19 @@
+class Starnose < Formula
+  include Language::Python::Virtualenv
+
+  desc "Context window observability for LLM agents"
+  homepage "https://github.com/eitanlebras/starnose"
+  url "https://files.pythonhosted.org/packages/source/s/starnose/starnose-0.1.0.tar.gz"
+  sha256 "UPDATE_WITH_REAL_SHA256"
+  license "MIT"
+
+  depends_on "python@3.12"
+
+  def install
+    virtualenv_install_with_resources
+  end
+
+  test do
+    assert_match "Context window observability", shell_output("#{bin}/snose --help")
+  end
+end

starnose-0.1.0/LICENSE

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

starnose-0.1.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.4
+Name: starnose
+Version: 0.1.0
+Summary: See exactly what your agent sees. Context window observability for LLM agents.
+Project-URL: Homepage, https://github.com/eitanlebras/starnose
+Project-URL: Repository, https://github.com/eitanlebras/starnose
+Project-URL: Issues, https://github.com/eitanlebras/starnose/issues
+Author: Eitan Lebras
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,anthropic,claude,context-window,llm,observability,openai,tokens
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Debuggers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: anthropic>=0.28
+Requires-Dist: cryptography>=42.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.30
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: textual>=0.60
+Requires-Dist: tiktoken>=0.7
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# starnose
+
+Your agent is running in the dark. starnose turns the lights on.
+
+`htop` for your agent's context window. Intercept, record, visualize, and compare the context sent to LLMs across agent runs — zero code changes required.
+
+![demo](demo.gif)
+
+## Install
+
+```bash
+pip install starnose
+```
+
+## Quick Start
+
+```bash
+# 1. Run your agent with context recording
+snose run python my_agent.py
+
+# 2. Inspect what your agent sent to the LLM
+snose inspect
+
+# 3. Compare two runs
+snose diff
+```
+
+That's it. No code changes. No config files. No API keys.
+
+## How It Works
+
+starnose starts a local proxy that intercepts all OpenAI and Anthropic API calls from your agent. It records every message, token count, and response to a local SQLite database. You then use the TUI tools to inspect, compare, and optimize your agent's context window usage.
+
+## Works With
+
+- **Claude Code** — `snose run -- claude`
+- **Codex CLI** — `snose run -- codex`
+- **LangChain** — callback handler included
+- **OpenAI SDK** — monkeypatch or proxy
+- **Anthropic SDK** — monkeypatch or proxy
+- **Any OpenAI-compatible agent** — `snose run -- <command>`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `snose run <cmd>` | Run a command with context interception |
+| `snose inspect [id]` | Inspect a run's context window (TUI) |
+| `snose diff [a] [b]` | Compare two runs side-by-side |
+| `snose watch` | Live-monitor a running agent |
+| `snose stats` | Aggregate stats across runs |
+| `snose optimize [id]` | Get optimization suggestions |
+| `snose ls` | List recorded runs |
+| `snose export [id]` | Export run data to JSON |
+| `snose config` | View/modify configuration |
+
+### snose run
+
+```bash
+snose run python my_agent.py
+snose run --name "gpt4-chunked" --tag prod python agent.py
+snose run --compare python agent.py    # auto-diff against last run
+```
+
+Flags:
+- `--name` — human-readable name
+- `--tag` — repeatable tags
+- `--model` — override model for token counting
+- `--compare` — auto-diff when complete
+- `--no-proxy` — disable interception
+
+### snose inspect
+
+```bash
+snose inspect              # most recent run
+snose inspect run_a2f3     # specific run
+snose inspect --last       # pick from recent runs
+```
+
+Two-panel TUI showing run metadata, context budget bar, segment breakdown, and full message details.
+
+### snose diff
+
+```bash
+snose diff                      # last two runs
+snose diff run_a2f3 run_9c81    # specific runs
+snose diff --last               # pick two runs
+```
+
+Shows segment-level delta table and auto-generated hypotheses explaining performance differences.
+
+### snose watch
+
+```bash
+snose watch    # attach to running agent
+```
+
+Live-streaming view of context changes as your agent runs.
+
+## Python SDK
+
+```python
+from starnose import trace, snapshot
+
+@trace(name="my-run", tags=["prod"])
+def my_agent(query: str) -> str:
+    ...
+
+# Or as context manager
+with trace("experiment-a") as run:
+    result = agent.run(query)
+    run.snapshot("pre-retrieval", messages)
+```
+
+## Integrations
+
+```python
+# OpenAI monkeypatch
+from starnose.integrations import patch_openai
+patch_openai()
+
+# Anthropic monkeypatch
+from starnose.integrations import patch_anthropic
+patch_anthropic()
+
+# LangChain callback
+from starnose.integrations import LangChainTracer
+agent = AgentExecutor(..., callbacks=[LangChainTracer()])
+```
+
+## Proxy Chaining
+
+If your agent already uses a proxy (e.g. LiteLLM):
+
+```bash
+STARNOSE_UPSTREAM=http://localhost:4000 snose run python agent.py
+```
+
+## Philosophy
+
+- **Local-first** — all data stays in `~/.starnose/runs.db`
+- **Zero code changes** — proxy-based interception, just wrap your command
+- **Pipe-friendly** — every command supports `--json` for scripting
+- **Never breaks your agent** — proxy errors fail open, always
+
+## Configuration
+
+```bash
+snose config                          # show current config
+snose config set model gpt-4o         # set default model
+snose config set context_limit 128000 # override context limit
+snose config reset                    # restore defaults
+```
+
+Config stored in `~/.starnose/config.json`.
+DB stored in `~/.starnose/runs.db` (override with `STARNOSE_DB` env var).

starnose-0.1.0/README.md

@@ -0,0 +1,156 @@
+# starnose
+
+Your agent is running in the dark. starnose turns the lights on.
+
+`htop` for your agent's context window. Intercept, record, visualize, and compare the context sent to LLMs across agent runs — zero code changes required.
+
+![demo](demo.gif)
+
+## Install
+
+```bash
+pip install starnose
+```
+
+## Quick Start
+
+```bash
+# 1. Run your agent with context recording
+snose run python my_agent.py
+
+# 2. Inspect what your agent sent to the LLM
+snose inspect
+
+# 3. Compare two runs
+snose diff
+```
+
+That's it. No code changes. No config files. No API keys.
+
+## How It Works
+
+starnose starts a local proxy that intercepts all OpenAI and Anthropic API calls from your agent. It records every message, token count, and response to a local SQLite database. You then use the TUI tools to inspect, compare, and optimize your agent's context window usage.
+
+## Works With
+
+- **Claude Code** — `snose run -- claude`
+- **Codex CLI** — `snose run -- codex`
+- **LangChain** — callback handler included
+- **OpenAI SDK** — monkeypatch or proxy
+- **Anthropic SDK** — monkeypatch or proxy
+- **Any OpenAI-compatible agent** — `snose run -- <command>`
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `snose run <cmd>` | Run a command with context interception |
+| `snose inspect [id]` | Inspect a run's context window (TUI) |
+| `snose diff [a] [b]` | Compare two runs side-by-side |
+| `snose watch` | Live-monitor a running agent |
+| `snose stats` | Aggregate stats across runs |
+| `snose optimize [id]` | Get optimization suggestions |
+| `snose ls` | List recorded runs |
+| `snose export [id]` | Export run data to JSON |
+| `snose config` | View/modify configuration |
+
+### snose run
+
+```bash
+snose run python my_agent.py
+snose run --name "gpt4-chunked" --tag prod python agent.py
+snose run --compare python agent.py    # auto-diff against last run
+```
+
+Flags:
+- `--name` — human-readable name
+- `--tag` — repeatable tags
+- `--model` — override model for token counting
+- `--compare` — auto-diff when complete
+- `--no-proxy` — disable interception
+
+### snose inspect
+
+```bash
+snose inspect              # most recent run
+snose inspect run_a2f3     # specific run
+snose inspect --last       # pick from recent runs
+```
+
+Two-panel TUI showing run metadata, context budget bar, segment breakdown, and full message details.
+
+### snose diff
+
+```bash
+snose diff                      # last two runs
+snose diff run_a2f3 run_9c81    # specific runs
+snose diff --last               # pick two runs
+```
+
+Shows segment-level delta table and auto-generated hypotheses explaining performance differences.
+
+### snose watch
+
+```bash
+snose watch    # attach to running agent
+```
+
+Live-streaming view of context changes as your agent runs.
+
+## Python SDK
+
+```python
+from starnose import trace, snapshot
+
+@trace(name="my-run", tags=["prod"])
+def my_agent(query: str) -> str:
+    ...
+
+# Or as context manager
+with trace("experiment-a") as run:
+    result = agent.run(query)
+    run.snapshot("pre-retrieval", messages)
+```
+
+## Integrations
+
+```python
+# OpenAI monkeypatch
+from starnose.integrations import patch_openai
+patch_openai()
+
+# Anthropic monkeypatch
+from starnose.integrations import patch_anthropic
+patch_anthropic()
+
+# LangChain callback
+from starnose.integrations import LangChainTracer
+agent = AgentExecutor(..., callbacks=[LangChainTracer()])
+```
+
+## Proxy Chaining
+
+If your agent already uses a proxy (e.g. LiteLLM):
+
+```bash
+STARNOSE_UPSTREAM=http://localhost:4000 snose run python agent.py
+```
+
+## Philosophy
+
+- **Local-first** — all data stays in `~/.starnose/runs.db`
+- **Zero code changes** — proxy-based interception, just wrap your command
+- **Pipe-friendly** — every command supports `--json` for scripting
+- **Never breaks your agent** — proxy errors fail open, always
+
+## Configuration
+
+```bash
+snose config                          # show current config
+snose config set model gpt-4o         # set default model
+snose config set context_limit 128000 # override context limit
+snose config reset                    # restore defaults
+```
+
+Config stored in `~/.starnose/config.json`.
+DB stored in `~/.starnose/runs.db` (override with `STARNOSE_DB` env var).

starnose-0.1.0/examples/test_agent.py

@@ -0,0 +1,127 @@
+"""Simple test agent that makes LLM calls through a built-in mock.
+
+No API key needed. Run with:
+  STARNOSE_OPENAI_UPSTREAM=http://127.0.0.1:19876 snose run python3 examples/test_agent.py
+"""
+
+import os
+import json
+import socket
+import http.server
+import threading
+import time
+
+import httpx
+
+
+# ── Start mock LLM server on a fixed port ────────────────────────────────────
+
+MOCK_PORT = 19876
+
+
+class MockLLMHandler(http.server.BaseHTTPRequestHandler):
+    call_count = 0
+
+    def do_POST(self):
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length)) if length else {}
+
+        MockLLMHandler.call_count += 1
+        messages = body.get("messages", [])
+        user_msg = next((m["content"] for m in reversed(messages) if m["role"] == "user"), "")
+
+        response = {
+            "id": f"chatcmpl-mock-{MockLLMHandler.call_count}",
+            "object": "chat.completion",
+            "model": body.get("model", "gpt-4o"),
+            "choices": [{
+                "index": 0,
+                "message": {
+                    "role": "assistant",
+                    "content": f"Mock response #{MockLLMHandler.call_count}: {user_msg[:80]}",
+                },
+                "finish_reason": "stop",
+            }],
+            "usage": {
+                "prompt_tokens": sum(len(m.get("content", "")) // 4 for m in messages),
+                "completion_tokens": 20,
+            },
+        }
+
+        data = json.dumps(response).encode()
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(data)))
+        self.end_headers()
+        self.wfile.write(data)
+
+    def log_message(self, *args):
+        pass
+
+
+mock_server = http.server.HTTPServer(("127.0.0.1", MOCK_PORT), MockLLMHandler)
+mock_thread = threading.Thread(target=mock_server.serve_forever, daemon=True)
+mock_thread.start()
+time.sleep(0.1)
+
+# ── Make calls through the starnose proxy ────────────────────────────────────
+
+base_url = os.environ.get("OPENAI_BASE_URL", f"http://127.0.0.1:{MOCK_PORT}/v1")
+api_key = os.environ.get("OPENAI_API_KEY", "test-key")
+
+print(f"proxy: {base_url}")
+print(f"run:   {os.environ.get('STARNOSE_RUN_ID', 'none')}")
+print()
+
+scenarios = [
+    {
+        "messages": [
+            {"role": "system", "content": "You are a research assistant. Use tools to find information. Always cite your sources. Be thorough."},
+            {"role": "user", "content": "What are the latest developments in quantum computing?"},
+        ],
+    },
+    {
+        "messages": [
+            {"role": "system", "content": "You are a research assistant. Use tools to find information. Always cite your sources. Be thorough."},
+            {"role": "user", "content": "What are the latest developments in quantum computing?"},
+            {"role": "assistant", "content": "I found several key developments in quantum computing..."},
+            {"role": "user", "content": "Tell me more about error correction breakthroughs."},
+            {"role": "tool", "content": "Search results for 'quantum error correction 2024':\n" + "Result entry with details about quantum research. " * 50},
+        ],
+    },
+    {
+        "messages": [
+            {"role": "system", "content": "You are a research assistant. Use tools to find information. Always cite your sources. Be thorough."},
+            {"role": "user", "content": "What are the latest developments in quantum computing?"},
+            {"role": "assistant", "content": "I found several key developments in quantum computing..."},
+            {"role": "user", "content": "Tell me more about error correction breakthroughs."},
+            {"role": "tool", "content": "Search results for 'quantum error correction 2024':\n" + "Result entry with details about quantum research. " * 50},
+            {"role": "assistant", "content": "Based on my research, here are the key error correction breakthroughs..."},
+            {"role": "user", "content": "Now write a comprehensive report. Include all raw data."},
+            {"role": "tool", "content": "Full database export:\n" + "Lorem ipsum dolor sit amet, consectetur adipiscing elit. " * 400},
+        ],
+    },
+]
+
+print(f"Making {len(scenarios)} LLM calls...\n")
+
+for i, scenario in enumerate(scenarios, 1):
+    resp = httpx.post(
+        f"{base_url}/chat/completions",
+        json={"model": "gpt-4o", "messages": scenario["messages"], "temperature": 0.7},
+        headers={"Authorization": f"Bearer {api_key}"},
+        timeout=10,
+    )
+
+    data = resp.json()
+    reply = data["choices"][0]["message"]["content"]
+    usage = data.get("usage", {})
+    print(f"  Call {i}: {usage.get('prompt_tokens', 0):>5} in / {usage.get('completion_tokens', 0):>3} out")
+    print(f"          → {reply[:70]}")
+    print()
+
+mock_server.shutdown()
+print("Done! Now try:")
+print("  snose inspect")
+print("  snose stats")
+print("  snose optimize")

starnose-0.1.0/examples/test_mitm.py

@@ -0,0 +1,62 @@
+"""Test the MITM proxy by making HTTPS requests through it.
+
+Run with: snose run --mitm python3 examples/test_mitm.py
+"""
+
+import os
+import ssl
+
+import httpx
+
+print(f"HTTPS_PROXY: {os.environ.get('HTTPS_PROXY', 'not set')}")
+print(f"Run ID: {os.environ.get('STARNOSE_RUN_ID', 'not set')}")
+print()
+
+# Build SSL context that trusts our CA
+ca_path = os.environ.get("NODE_EXTRA_CA_CERTS")
+if ca_path:
+    ssl_ctx = ssl.create_default_context()
+    ssl_ctx.load_verify_locations(ca_path)
+    # Also load default system CAs for non-intercepted hosts
+    ssl_ctx.load_default_certs()
+    verify = ssl_ctx
+    print(f"Using CA: {ca_path}")
+else:
+    verify = True
+    print("No custom CA set, using defaults")
+
+print()
+
+# Test 1: Anthropic API interception
+# The request will be intercepted by the MITM proxy, forwarded to the real
+# api.anthropic.com, and the response recorded. Auth will fail (no real key)
+# but starnose still records the request.
+print("Test: Anthropic API call through MITM proxy...")
+try:
+    resp = httpx.post(
+        "https://api.anthropic.com/v1/messages",
+        headers={
+            "x-api-key": "test-key-not-real",
+            "anthropic-version": "2023-06-01",
+            "content-type": "application/json",
+        },
+        json={
+            "model": "claude-3-haiku-20240307",
+            "max_tokens": 100,
+            "messages": [
+                {"role": "user", "content": "Hello, this is a test of starnose MITM!"}
+            ],
+        },
+        verify=verify,
+        timeout=15,
+    )
+    print(f"  Status: {resp.status_code}")
+    print(f"  (401 expected — no real API key, but request was intercepted)")
+except httpx.ConnectError as e:
+    print(f"  ConnectError: {e}")
+    print("  (If SSL error: run 'snose setup' to trust the CA)")
+except Exception as e:
+    print(f"  {type(e).__name__}: {e}")
+
+print()
+print("Done! Run 'snose inspect' to see recorded calls.")