spooling 0.1.5__tar.gz → 0.1.7__tar.gz

spooling-0.1.7/PKG-INFO

@@ -0,0 +1,34 @@
+Metadata-Version: 2.4
+Name: spooling
+Version: 0.1.7
+Summary: Local session tracker and semantic search for AI coding assistants
+Author: Parsed Analytics, Inc.
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.11
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: psycopg[binary]>=3.1
+Requires-Dist: sentence-transformers>=3.0
+Requires-Dist: fastapi>=0.111
+Requires-Dist: uvicorn[standard]>=0.30
+Requires-Dist: jinja2>=3.1
+Requires-Dist: watchdog>=4.0
+Requires-Dist: rich>=13.0
+Requires-Dist: httpx>=0.27
+Requires-Dist: anthropic>=0.40
+Requires-Dist: strands-agents[ollama]>=1.35
+Requires-Dist: strands-agents-evals>=0.1
+Requires-Dist: mcp>=1.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.14; extra == "dev"
+Provides-Extra: connectors
+Requires-Dist: snowflake-connector-python>=3.0; extra == "connectors"
+Requires-Dist: google-cloud-bigquery>=3.0; extra == "connectors"
+Requires-Dist: mysql-connector-python>=8.0; extra == "connectors"
+Requires-Dist: clickhouse-connect>=0.5; extra == "connectors"
+Requires-Dist: motor>=3.0; extra == "connectors"
+Dynamic: license-file

spooling-0.1.5/spooling.egg-info/PKG-INFO → spooling-0.1.7/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: spooling
-Version: 0.1.5
-Summary: Local session tracker and semantic search for AI coding assistants
-Author: Parsed Analytics, Inc.
-License-Expression: MIT
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: click>=8.1
-Requires-Dist: psycopg[binary]>=3.1
-Requires-Dist: sentence-transformers>=3.0
-Requires-Dist: fastapi>=0.111
-Requires-Dist: uvicorn[standard]>=0.30
-Requires-Dist: jinja2>=3.1
-Requires-Dist: watchdog>=4.0
-Requires-Dist: rich>=13.0
-Requires-Dist: httpx>=0.27
-Requires-Dist: anthropic>=0.40
-Requires-Dist: strands-agents[ollama]>=1.35
-Requires-Dist: strands-agents-evals>=0.1
-Requires-Dist: mcp>=1.27
-Provides-Extra: dev
-Requires-Dist: pytest>=8.0; extra == "dev"
-Requires-Dist: pytest-mock>=3.14; extra == "dev"
-Dynamic: license-file
-
 # Spooling
 
 Local session tracker and semantic search for AI coding assistants.
@@ -221,6 +191,110 @@ spooling mcp              # streamable-HTTP at http://127.0.0.1:3004/mcp (defaul
 spooling mcp --stdio      # stdio transport, for stdio-only clients
 ```
 
+### `spooling tunnel`
+
+Create a Cloudflare quick tunnel (no account required) to expose your local MCP server to the internet. Once started, it prints a public HTTPS URL you can drop straight into any remote MCP client config. Requires [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) to be installed.
+
+```bash
+spooling tunnel                    # Expose Spooling MCP (port 3004, default)
+spooling tunnel --port 8090        # Expose a custom local port
+spooling tunnel -p 3000 -n my-api  # Named tunnel on port 3000
+```
+
+Options:
+- `-p, --port` - Local port to expose (default: 3004)
+- `-n, --name` - Label for display purposes
+
+After the tunnel starts, it prints the public URL and an MCP config snippet ready to paste:
+
+```json
+{"mcpServers": {"spooling": {"type": "http", "url": "https://<random>.trycloudflare.com/mcp"}}}
+```
+
+Install `cloudflared` if not already present:
+
+```bash
+# macOS
+brew install cloudflared
+
+# Linux
+curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 \
+  -o /usr/local/bin/cloudflared && chmod +x /usr/local/bin/cloudflared
+
+# Windows
+winget install cloudflare.cloudflared
+```
+
+### `spooling cost`
+
+Detailed cost tracking and spend analysis. All subcommands read from the local database — no network calls.
+
+```bash
+spooling cost overview                          # Total spend: input/output/cache breakdown
+spooling cost overview --provider cursor        # Filter to one provider
+spooling cost overview --days 7                 # Last 7 days only
+
+spooling cost breakdown                         # Cost by provider (default)
+spooling cost breakdown --by model              # Cost by model
+spooling cost breakdown --by project            # Cost by project
+spooling cost breakdown --by model --days 30    # Model breakdown, last 30 days
+
+spooling cost daily                             # Daily trend (last 30 days)
+spooling cost daily --days 14                   # Last 14 days
+spooling cost daily --provider codex            # Filter by provider
+
+spooling cost monthly                           # Monthly trend (last 12 months)
+spooling cost monthly --months 6                # Last 6 months
+
+spooling cost session <session-id>              # Detailed cost for a single session
+
+spooling cost recalc                            # Dry-run: re-price all sessions against current rates
+spooling cost recalc --apply                    # Actually persist the repriced values
+spooling cost recalc --session <id> --apply     # Reprice one session
+spooling cost recalc --provider cursor --apply  # Reprice all sessions for a provider
+```
+
+### `spooling eval`
+
+Run LLM-as-judge rubrics against your session traces.
+
+```bash
+spooling eval list                              # List all configured rubrics
+spooling eval run --rubric <id> --trace <id>    # Score one trace
+spooling eval run --rubric <id> --days 7        # Batch-score traces from the last 7 days
+```
+
+### `spooling experiment`
+
+Create and run Strands-style experiments — a set of test cases evaluated by one or more rubrics.
+
+```bash
+spooling experiment list                        # List all experiments
+spooling experiment create --file spec.json     # Register an experiment from a JSON spec
+spooling experiment run --id <experiment-id>    # Run an experiment and persist the report
+spooling experiment show --run <run-id>         # Show the results of a past run
+```
+
+### `spooling otel`
+
+Ingest OpenTelemetry / Strands span exports from external sources into Spooling.
+
+```bash
+spooling otel ingest --file spans.json                         # Ingest an OTLP JSON export
+spooling otel ingest --file spans.json --provider my-agent     # Tag with a custom provider id
+spooling otel ingest --file spans.json --project myproject     # Tag with a project name
+```
+
+### `spooling pricing`
+
+Manage the LiteLLM-backed model pricing table used for cost calculations.
+
+```bash
+spooling pricing show                           # Show cache status and source info
+spooling pricing show claude-sonnet-4-5         # Show per-component rates for a model ($/Mtok)
+spooling pricing refresh                        # Force-fetch latest rates into ~/.spool/model_prices.json
+```
+
 ---
 
 ## Spooling Cloud (optional)
@@ -457,6 +531,7 @@ spooling/
 │   ├── stats.py             # Usage statistics
 │   ├── watcher.py           # File watcher (watchdog)
 │   ├── agent.py             # Chat agent (Ollama + Anthropic)
+│   ├── tunnel.py            # Cloudflare quick tunnel support
 │   └── server.py            # FastAPI API server
 └── ui/                      # Next.js frontend
     ├── next.config.js       # API proxy to :3002
@@ -521,3 +596,4 @@ All optional - defaults work out of the box for local development.
 Run `spooling init` to see which providers are detected on your system.
 
 No data is sent to external servers. Everything runs locally.
+

{spooling-0.1.5 → spooling-0.1.7}/pyproject.toml

@@ -1,17 +1,15 @@
 [project]
 name = "spooling"
-version = "0.1.5"
+version = "0.1.7"
 description = "Local session tracker and semantic search for AI coding assistants"
-readme = "README.md"
-license = "MIT"
-license-files = ["LICENSE"]
 authors = [{ name = "Parsed Analytics, Inc." }]
+license = { text = "MIT" }
+requires-python = ">=3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
 ]
-requires-python = ">=3.11"
 dependencies = [
     "click>=8.1",
     "psycopg[binary]>=3.1",
@@ -28,21 +26,29 @@ dependencies = [
     "mcp>=1.27",
 ]
 
-[project.scripts]
-spooling = "spooling.cli:cli"
-
-[tool.setuptools.packages.find]
-include = ["spooling*"]
-
 [project.optional-dependencies]
 dev = [
     "pytest>=8.0",
     "pytest-mock>=3.14",
 ]
+connectors = [
+    "snowflake-connector-python>=3.0",
+    "google-cloud-bigquery>=3.0",
+    "mysql-connector-python>=8.0",
+    "clickhouse-connect>=0.5",
+    "motor>=3.0",
+]
 
-[tool.pytest.ini_options]
-testpaths = ["tests"]
+[project.scripts]
+spooling = "spooling.cli:cli"
 
 [build-system]
-requires = ["setuptools>=68"]
+requires = ["setuptools>=68", "wheel"]
 build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spooling*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

{spooling-0.1.5 → spooling-0.1.7}/spooling/cli.py

@@ -83,17 +83,22 @@ def watch():
 @click.argument("query")
 @click.option("-n", "--limit", default=10, help="Number of results")
 @click.option("-p", "--project", default=None, help="Filter by project")
-def search(query, limit, project):
+@click.option("--cloud", "cloud_mode", is_flag=True, help="Search cloud workspace instead of local DB")
+def search(query, limit, project, cloud_mode):
     """Semantic search across session history."""
-    from spooling.search import search as do_search
-
-    results = do_search(query, limit=limit, project=project)
+    if cloud_mode:
+        from spooling.cloud import cloud_search
+        results = cloud_search(query, limit=limit, project=project)
+    else:
+        from spooling.search import search as do_search
+        results = do_search(query, limit=limit, project=project)
 
     if not results:
         console.print("[yellow]No results found.[/yellow]")
         return
 
     for i, r in enumerate(results, 1):
+        source = r.get("_source", "local")
         similarity = f"{r['similarity']:.1%}"
         project_name = r["project"] or "unknown"
         role = r["role"]
@@ -104,6 +109,7 @@ def search(query, limit, project):
             f"[dim]{project_name}[/dim] "
             f"[{'green' if role == 'user' else 'blue'}]{role}[/{'green' if role == 'user' else 'blue'}] "
             f"[dim]{ts[:19]}[/dim]"
+            + (f" [cyan](cloud)[/cyan]" if source == "cloud" else "")
         )
         if r["title"]:
             console.print(f"   [dim]Session:[/dim] {r['title']}")
@@ -113,8 +119,23 @@ def search(query, limit, project):
 @cli.command()
 @click.option("--week", is_flag=True, help="Show weekly breakdown")
 @click.option("--days", default=7, help="Number of days for daily stats")
-def stats(week, days):
+@click.option("--cloud", "cloud_mode", is_flag=True, help="Show stats from cloud workspace")
+def stats(week, days, cloud_mode):
     """Show usage statistics."""
+    if cloud_mode:
+        from spooling.cloud import cloud_stats
+        data = cloud_stats()
+        if not data:
+            console.print("[yellow]No cloud stats available. Run 'spooling cloud login' first.[/yellow]")
+            return
+        console.print(Panel(
+            f"Sessions: [bold]{data.get('sessions', 0)}[/bold]  |  "
+            f"Cost: [bold]${float(data.get('cost', 0)):.2f}[/bold] est.",
+            title="[bold]Spooling Cloud Overview[/bold]",
+            style="cyan",
+        ))
+        return
+
     from spooling.stats import get_overview, get_daily_stats
 
     overview = get_overview()
@@ -657,23 +678,62 @@ def pricing_show(model):
     console.print(table)
 
 
+@cli.command()
+@click.option("--port", "-p", default=3004, type=int, help="Local port to tunnel (default: 3004 for Spooling MCP)")
+@click.option("--name", "-n", default=None, help="Name for this tunnel (for display)")
+def tunnel(port, name):
+    """Start a Cloudflare tunnel to expose a local MCP server.
+
+    Creates a quick tunnel (no account required) that exposes your local
+    MCP server to the internet. The tunnel URL can be used by any
+    MCP-compatible client.
+
+    Examples:
+    \b
+    spooling tunnel                    # Tunnel Spooling MCP (port 3004)
+    spooling tunnel --port 8090        # Tunnel a custom MCP server
+    spooling tunnel -p 3000 -n my-api  # Named tunnel
+    """
+    from spooling.tunnel import start_tunnel
+
+    display_name = name or f"port {port}"
+    console.print(f"[bold]Starting tunnel for {display_name}...[/bold]")
+
+    url = start_tunnel(port=port, name=name)
+    if url:
+        # Print MCP config snippet for easy copy-paste
+        console.print()
+        console.print("[dim]Add this to your MCP client config:[/dim]")
+        console.print(f'[bold]{{"mcpServers": {{"custom": {{"type": "http", "url": "{url}/mcp"}}}}}}[/bold]')
+        console.print()
+
+
 @cli.command()
 @click.option("--stdio", is_flag=True, help="Use stdio transport (default is streamable-HTTP)")
-def mcp(stdio):
+@click.option("--local", "local_mode", flag_value="local", default=True, help="Local DB only, no cloud fallback")
+@click.option("--cloud", "local_mode", flag_value="cloud", help="Cloud only, skip local DB")
+@click.option("--hybrid", "local_mode", flag_value="hybrid", help="Local DB with cloud fallback (default)")
+def mcp(stdio, local_mode):
     """Launch the Spooling MCP server.
 
     Defaults to streamable-HTTP at http://127.0.0.1:3004/mcp so any
     MCP-compatible agent (Codex, Cursor, web agents) can
     connect by URL. Pass --stdio for stdio-only clients.
+
+    Data source modes:
+    \b
+    --hybrid   Local DB with cloud fallback (default)
+    --local    Local DB only
+    --cloud    Cloud only
     """
+    from spooling.mcp_server import set_mode, serve_http as _serve_http, serve_stdio as _serve_stdio, MCP_URL
+    set_mode(local_mode or "hybrid")
     if stdio:
-        from spooling.mcp_server import serve_stdio
         console.print("[bold]Spooling MCP[/bold] over stdio")
-        serve_stdio()
+        _serve_stdio()
     else:
-        from spooling.mcp_server import serve_http, MCP_URL
         console.print(f"[bold]Spooling MCP[/bold] at {MCP_URL}")
-        serve_http()
+        _serve_http()
 
 
 def _check_ollama_preflight() -> None: