scaffold: cobra CLI skeleton, package layout, project thesis

Initial scaffolding for llmtrace — self-hosted LLM proxy with cost ledger
and deploy-to-spend causal attribution. Same architectural pattern as
costtrace (anomaly detection + GitHub Actions deploy correlation +
lineage scoring) applied to LLM provider APIs instead of AWS spend.

CLI commands stubbed: serve, keys, stats, tail, anomalies, analyze,
explain, report. All return notImplemented errors — real work begins
week 1 (proxy + Anthropic provider + ledger).

See CLAUDE.md (gitignored) for the 3-week MVP scope and differentiation
vs Helicone/Portkey/LiteLLM/Langfuse.

.gitignore

@@ -0,0 +1,9 @@
+/llmtrace
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+config.toml
+.env
+.envrc
+CLAUDE.md

LICENSE

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

README.md

@@ -0,0 +1,29 @@
+# llmtrace
+
+Deploy-to-LLM-spend causal attribution.
+
+> Which prompt change caused this $4k/week spike?
+
+`llmtrace` is a self-hosted reverse proxy for LLM provider APIs (Anthropic, OpenAI, Bedrock) with a built-in cost ledger, latency tracking, and anomaly detection. It joins LLM spend anomalies to the deploy events that caused them — using the same architectural pattern as [costtrace](https://github.com/Yatsuiii/costtrace) does for AWS spend.
+
+**Status: scaffolding.** See `CLAUDE.md` (gitignored) for the project thesis. Tracking issues against the 3-week MVP scope.
+
+## How it works (planned)
+
+1. **Proxy** — your code points at `llmtrace serve` instead of `api.anthropic.com`. It forwards requests upstream and records token usage, cost, latency, model, and prompt fingerprint per call.
+2. **Detect** — flags per-key spend/latency anomalies using a rolling baseline + sigma threshold.
+3. **Correlate** — matches anomalies to GitHub Actions deploys, scores confidence based on model-change / prompt-change evidence.
+
+## How it differs from other tools
+
+| Tool | What it does | What it misses |
+|---|---|---|
+| Helicone | Hosted observability + caching | Hosted-only, no deploy correlation |
+| Portkey | AI gateway with routing/caching | Feature-stew, no anomaly attribution |
+| LiteLLM | Open-source proxy | No anomaly detection, no deploy join |
+| Langfuse | LLM observability platform | Trace-focused, not cost-focused |
+| **llmtrace** | **Deploy → LLM-spend causal chain** | MVP: Anthropic only, single tenant |
+
+## License
+
+MIT

cmd/llmtrace/main.go

@@ -0,0 +1,165 @@
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/spf13/cobra"
+)
+
+func main() {
+	root := &cobra.Command{
+		Use:   "llmtrace",
+		Short: "LLM call tracing with cost & latency anomaly detection",
+	}
+	root.AddCommand(
+		cmdInit(),
+		cmdServe(),
+		cmdKeys(),
+		cmdStats(),
+		cmdTail(),
+		cmdAnomalies(),
+		cmdAnalyze(),
+		cmdExplain(),
+		cmdReport(),
+	)
+	if err := root.Execute(); err != nil {
+		os.Exit(1)
+	}
+}
+
+func cmdInit() *cobra.Command {
+	return &cobra.Command{
+		Use:   "init",
+		Short: "Interactive setup → config.toml",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("init")
+		},
+	}
+}
+
+func cmdServe() *cobra.Command {
+	var port int
+	cmd := &cobra.Command{
+		Use:   "serve",
+		Short: "Run the proxy server",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("serve")
+		},
+	}
+	cmd.Flags().IntVar(&port, "port", 8080, "listen port")
+	return cmd
+}
+
+func cmdKeys() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:   "keys",
+		Short: "Manage inbound API keys",
+	}
+	cmd.AddCommand(
+		&cobra.Command{
+			Use:   "add",
+			Short: "Mint a new API key",
+			RunE: func(cmd *cobra.Command, args []string) error {
+				return notImplemented("keys add")
+			},
+		},
+		&cobra.Command{
+			Use:   "list",
+			Short: "List API keys",
+			RunE: func(cmd *cobra.Command, args []string) error {
+				return notImplemented("keys list")
+			},
+		},
+		&cobra.Command{
+			Use:   "revoke <key-id>",
+			Short: "Revoke an API key",
+			Args:  cobra.ExactArgs(1),
+			RunE: func(cmd *cobra.Command, args []string) error {
+				return notImplemented("keys revoke")
+			},
+		},
+	)
+	return cmd
+}
+
+func cmdStats() *cobra.Command {
+	var days int
+	cmd := &cobra.Command{
+		Use:   "stats",
+		Short: "Ledger summary by key/model",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("stats")
+		},
+	}
+	cmd.Flags().IntVar(&days, "days", 7, "window in days")
+	return cmd
+}
+
+func cmdTail() *cobra.Command {
+	return &cobra.Command{
+		Use:   "tail",
+		Short: "Live request stream",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("tail")
+		},
+	}
+}
+
+func cmdAnomalies() *cobra.Command {
+	var days int
+	var format string
+	cmd := &cobra.Command{
+		Use:   "anomalies",
+		Short: "List spend/latency anomalies",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("anomalies")
+		},
+	}
+	cmd.Flags().IntVar(&days, "days", 30, "window to scan for anomalies")
+	cmd.Flags().StringVar(&format, "format", "text", "output format: text | markdown")
+	return cmd
+}
+
+func cmdAnalyze() *cobra.Command {
+	var days int
+	cmd := &cobra.Command{
+		Use:   "analyze",
+		Short: "Anomalies + deploy correlations",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("analyze")
+		},
+	}
+	cmd.Flags().IntVar(&days, "days", 30, "window to analyze")
+	return cmd
+}
+
+func cmdExplain() *cobra.Command {
+	return &cobra.Command{
+		Use:   "explain <anomaly-id>",
+		Short: "Deep-dive a single anomaly",
+		Args:  cobra.ExactArgs(1),
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("explain")
+		},
+	}
+}
+
+func cmdReport() *cobra.Command {
+	var days int
+	var format string
+	cmd := &cobra.Command{
+		Use:   "report",
+		Short: "Polished report",
+		RunE: func(cmd *cobra.Command, args []string) error {
+			return notImplemented("report")
+		},
+	}
+	cmd.Flags().IntVar(&days, "days", 30, "window to report on")
+	cmd.Flags().StringVar(&format, "format", "text", "output format: text | markdown")
+	return cmd
+}
+
+func notImplemented(name string) error {
+	return fmt.Errorf("%s: not implemented yet — see CLAUDE.md for the 3-week scope", name)
+}

examples/basic-config.toml

@@ -0,0 +1,26 @@
+[proxy]
+listen = "0.0.0.0:8080"
+tls_cert = ""
+tls_key = ""
+
+[providers.anthropic]
+upstream_url = "https://api.anthropic.com"
+upstream_key_env = "ANTHROPIC_API_KEY"
+
+[providers.openai]
+upstream_url = "https://api.openai.com"
+upstream_key_env = "OPENAI_API_KEY"
+
+[github]
+repo = "org/name"
+token_env = "GITHUB_TOKEN"
+deploy_workflow_pattern = "deploy.*"
+
+[detection]
+baseline_days = 7
+sigma_threshold = 2.5
+min_delta_usd = 5
+correlation_window_hours = 4
+
+[output]
+format = "text"

go.mod

@@ -0,0 +1,10 @@
+module github.com/Yatsuiii/llmtrace
+
+go 1.26.2
+
+require github.com/spf13/cobra v1.10.2
+
+require (
+	github.com/inconshreveable/mousetrap v1.1.0 // indirect
+	github.com/spf13/pflag v1.0.9 // indirect
+)

go.sum

@@ -0,0 +1,10 @@
+github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
+github.com/inconshreveable/mousetrap v1.1.0 h1:wN+x4NVGpMsO7ErUn/mUI3vEoE6Jt13X2s0bqwp9tc8=
+github.com/inconshreveable/mousetrap v1.1.0/go.mod h1:vpF70FUmC8bwa3OWnCshd2FqLfsEA9PFc4w1p2J65bw=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/spf13/cobra v1.10.2 h1:DMTTonx5m65Ic0GOoRY2c16WCbHxOOw6xxezuLaBpcU=
+github.com/spf13/cobra v1.10.2/go.mod h1:7C1pvHqHw5A4vrJfjNwvOdzYu0Gml16OCs2GRiTUUS4=
+github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
+github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
+go.yaml.in/yaml/v3 v3.0.4/go.mod h1:DhzuOOF2ATzADvBadXxruRBLzYTpT36CKvDb3+aBEFg=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/config/config.go

@@ -0,0 +1,70 @@
+package config
+
+type Config struct {
+	Proxy     ProxyConfig
+	Providers ProvidersConfig
+	GitHub    GitHubConfig
+	Detection DetectionConfig
+	Output    OutputConfig
+}
+
+type ProxyConfig struct {
+	Listen  string
+	TLSCert string
+	TLSKey  string
+}
+
+type ProvidersConfig struct {
+	Anthropic ProviderConfig
+	OpenAI    ProviderConfig
+	Bedrock   ProviderConfig
+}
+
+type ProviderConfig struct {
+	UpstreamURL    string
+	UpstreamKeyEnv string
+}
+
+type GitHubConfig struct {
+	Repo                  string
+	TokenEnv              string
+	DeployWorkflowPattern string
+}
+
+type DetectionConfig struct {
+	BaselineDays           int
+	SigmaThreshold         float64
+	MinDeltaUSD            float64
+	CorrelationWindowHours int
+}
+
+type OutputConfig struct {
+	Format string
+}
+
+func Defaults() *Config {
+	return &Config{
+		Proxy: ProxyConfig{Listen: "0.0.0.0:8080"},
+		Providers: ProvidersConfig{
+			Anthropic: ProviderConfig{
+				UpstreamURL:    "https://api.anthropic.com",
+				UpstreamKeyEnv: "ANTHROPIC_API_KEY",
+			},
+			OpenAI: ProviderConfig{
+				UpstreamURL:    "https://api.openai.com",
+				UpstreamKeyEnv: "OPENAI_API_KEY",
+			},
+		},
+		GitHub: GitHubConfig{
+			TokenEnv:              "GITHUB_TOKEN",
+			DeployWorkflowPattern: "deploy.*",
+		},
+		Detection: DetectionConfig{
+			BaselineDays:           7,
+			SigmaThreshold:         2.5,
+			MinDeltaUSD:            5,
+			CorrelationWindowHours: 4,
+		},
+		Output: OutputConfig{Format: "text"},
+	}
+}

internal/detect/anomaly.go

@@ -0,0 +1,10 @@
+package detect
+
+// Detect logic lives here. Implemented week 2.
+// Placeholder so the package compiles.
+
+type Config struct {
+	BaselineDays   int
+	SigmaThreshold float64
+	MinDeltaUSD    float64
+}

internal/pricing/rates.go

@@ -0,0 +1,27 @@
+package pricing
+
+type ModelRate struct {
+	InputPerMillion  float64
+	OutputPerMillion float64
+}
+
+var rates = map[string]ModelRate{
+	// Anthropic — placeholder, refresh against official docs before shipping
+	"claude-opus-4-7":          {InputPerMillion: 15.00, OutputPerMillion: 75.00},
+	"claude-sonnet-4-6":        {InputPerMillion: 3.00, OutputPerMillion: 15.00},
+	"claude-haiku-4-5-20251001": {InputPerMillion: 0.80, OutputPerMillion: 4.00},
+}
+
+func Lookup(model string) (ModelRate, bool) {
+	r, ok := rates[model]
+	return r, ok
+}
+
+func Cost(model string, inputTokens, outputTokens int) float64 {
+	r, ok := Lookup(model)
+	if !ok {
+		return 0
+	}
+	return float64(inputTokens)*r.InputPerMillion/1_000_000 +
+		float64(outputTokens)*r.OutputPerMillion/1_000_000
+}

internal/providers/provider.go

@@ -0,0 +1,16 @@
+package providers
+
+import "net/http"
+
+type Provider interface {
+	Name() string
+	UpstreamURL() string
+	RoutePrefixes() []string
+	ParseUsage(req *http.Request, respBody []byte) (Usage, error)
+}
+
+type Usage struct {
+	Model        string
+	InputTokens  int
+	OutputTokens int
+}

internal/proxy/server.go

@@ -0,0 +1,11 @@
+package proxy
+
+import "github.com/Yatsuiii/llmtrace/internal/config"
+
+type Server struct {
+	cfg *config.Config
+}
+
+func New(cfg *config.Config) *Server {
+	return &Server{cfg: cfg}
+}

internal/ratelimit/limiter.go

@@ -0,0 +1,4 @@
+package ratelimit
+
+// Token-bucket per API key. Implemented week 2.
+type Limiter struct{}

internal/report/text.go

@@ -0,0 +1,3 @@
+package report
+
+// CLI text rendering. Implemented week 1.

internal/storage/schema.go

@@ -0,0 +1,71 @@
+package storage
+
+const schema = `
+CREATE TABLE IF NOT EXISTS calls (
+    id            INTEGER PRIMARY KEY AUTOINCREMENT,
+    timestamp     INTEGER NOT NULL,
+    api_key_id    TEXT NOT NULL,
+    provider      TEXT NOT NULL,
+    model         TEXT NOT NULL,
+    endpoint      TEXT NOT NULL,
+    input_tokens  INTEGER NOT NULL,
+    output_tokens INTEGER NOT NULL,
+    cost_usd      REAL NOT NULL,
+    latency_ms    INTEGER NOT NULL,
+    status        INTEGER NOT NULL,
+    error_class   TEXT NOT NULL DEFAULT '',
+    prompt_hash   TEXT NOT NULL DEFAULT '',
+    session_id    TEXT NOT NULL DEFAULT ''
+);
+CREATE INDEX IF NOT EXISTS calls_ts_idx ON calls(timestamp);
+CREATE INDEX IF NOT EXISTS calls_key_ts_idx ON calls(api_key_id, timestamp);
+
+CREATE TABLE IF NOT EXISTS api_keys (
+    id            TEXT PRIMARY KEY,
+    hashed_key    TEXT NOT NULL,
+    label         TEXT NOT NULL DEFAULT '',
+    budget_usd    REAL NOT NULL DEFAULT 0,
+    rate_limit_rpm INTEGER NOT NULL DEFAULT 0,
+    active        INTEGER NOT NULL DEFAULT 1,
+    created_at    INTEGER NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS anomalies (
+    id              INTEGER PRIMARY KEY AUTOINCREMENT,
+    detected_at     INTEGER NOT NULL,
+    api_key_id      TEXT NOT NULL,
+    date            TEXT NOT NULL,
+    metric          TEXT NOT NULL,
+    baseline_value  REAL NOT NULL,
+    actual_value    REAL NOT NULL,
+    delta           REAL NOT NULL,
+    sigma           REAL NOT NULL,
+    sample_size     INTEGER NOT NULL,
+    UNIQUE(api_key_id, date, metric)
+);
+
+CREATE TABLE IF NOT EXISTS deploys (
+    id            TEXT PRIMARY KEY,
+    repo          TEXT NOT NULL,
+    branch        TEXT NOT NULL,
+    commit_sha    TEXT NOT NULL,
+    pr_number     INTEGER,
+    title         TEXT NOT NULL,
+    started_at    INTEGER NOT NULL,
+    completed_at  INTEGER NOT NULL,
+    status        TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS correlations (
+    anomaly_id    INTEGER NOT NULL,
+    deploy_id     TEXT NOT NULL,
+    confidence    REAL NOT NULL,
+    evidence      TEXT NOT NULL,
+    PRIMARY KEY (anomaly_id, deploy_id)
+);
+
+CREATE TABLE IF NOT EXISTS sync_cursors (
+    name  TEXT PRIMARY KEY,
+    value TEXT NOT NULL
+);
+`

internal/storage/sqlite.go

@@ -0,0 +1,47 @@
+package storage
+
+import "time"
+
+type DB struct {
+	// to be implemented in week 1
+}
+
+type CallRow struct {
+	ID           int64
+	Timestamp    time.Time
+	APIKeyID     string
+	Provider     string
+	Model        string
+	Endpoint     string
+	InputTokens  int
+	OutputTokens int
+	CostUSD      float64
+	LatencyMs    int64
+	Status       int
+	ErrorClass   string
+	PromptHash   string
+	SessionID    string
+}
+
+type APIKeyRow struct {
+	ID           string
+	HashedKey    string
+	Label        string
+	BudgetUSD    float64
+	RateLimitRPM int
+	Active       bool
+	CreatedAt    time.Time
+}
+
+type AnomalyRow struct {
+	ID            int64
+	DetectedAt    time.Time
+	APIKeyID      string
+	Date          string
+	Metric        string
+	BaselineValue float64
+	ActualValue   float64
+	Delta         float64
+	Sigma         float64
+	SampleSize    int64
+}