kompact 0.1.0__py3-none-any.whl

kompact/__init__.py

@@ -0,0 +1,3 @@
+"""Kompact — Multi-layer context optimization proxy for LLM agents."""
+
+__version__ = "0.1.0"

kompact/__main__.py

@@ -0,0 +1,73 @@
+"""CLI entry point for Kompact."""
+
+import click
+
+
+@click.group()
+def cli():
+    """Kompact — Multi-layer context optimization proxy for LLM agents."""
+    pass
+
+
+@cli.command()
+@click.option("--port", default=7878, help="Port to listen on")
+@click.option("--host", default="0.0.0.0", help="Host to bind to")
+@click.option("--verbose", is_flag=True, help="Enable verbose logging")
+@click.option(
+    "--disable",
+    multiple=True,
+    help="Disable a transform (e.g. --disable toon --disable log_compressor)",
+)
+@click.option(
+    "--anthropic-base-url",
+    default="https://api.anthropic.com",
+    help="Upstream Anthropic API URL",
+)
+@click.option(
+    "--openai-base-url",
+    default="https://api.openai.com",
+    help="Upstream OpenAI API URL",
+)
+def proxy(
+    port: int,
+    host: str,
+    verbose: bool,
+    disable: tuple[str, ...],
+    anthropic_base_url: str,
+    openai_base_url: str,
+):
+    """Start the Kompact optimization proxy."""
+    import uvicorn
+
+    from kompact.config import KompactConfig
+    from kompact.proxy.server import create_app
+
+    config = KompactConfig(
+        host=host,
+        port=port,
+        verbose=verbose,
+        anthropic_base_url=anthropic_base_url,
+        openai_base_url=openai_base_url,
+    )
+
+    # Disable requested transforms
+    for name in disable:
+        transform_config = getattr(config, name, None)
+        if transform_config and hasattr(transform_config, "enabled"):
+            transform_config.enabled = False
+        else:
+            click.echo(f"Warning: Unknown transform '{name}'", err=True)
+
+    app = create_app(config)
+
+    click.echo(f"Kompact proxy starting on {host}:{port}")
+    click.echo(f"  Anthropic upstream: {anthropic_base_url}")
+    click.echo(f"  OpenAI upstream: {openai_base_url}")
+    click.echo(f"  Disabled transforms: {', '.join(disable) or 'none'}")
+    click.echo(f"  Dashboard: http://{host}:{port}/dashboard")
+
+    uvicorn.run(app, host=host, port=port, log_level="info" if verbose else "warning")
+
+
+if __name__ == "__main__":
+    cli()

kompact/cache/store.py

@@ -0,0 +1,224 @@
+"""Compression store for CCR-style content retrieval.
+
+Stores original content replaced by compression markers, allowing the LLM
+to request full content back when needed.
+
+Features:
+- Statistical summary in markers (not just token count)
+- Adaptive TTL based on access frequency
+- In-memory with bounded size (LRU eviction)
+- Artifact index tracking what was compressed (kind, key, summary, turn)
+"""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class ArtifactEntry:
+    """A tracked artifact that was compressed/masked."""
+
+    kind: str  # "tool_result", "file", "search", "log", "code"
+    key: str  # identifier (tool name, file path, etc.)
+    summary: str  # brief description of what was stored
+    turn_id: int  # conversation turn where this appeared
+    store_key: str = ""  # key in the compression store for retrieval
+
+
+@dataclass
+class ArtifactIndex:
+    """Persistent index of compressed artifacts for re-fetching."""
+
+    entries: list[ArtifactEntry] = field(default_factory=list)
+
+    def add(
+        self,
+        kind: str,
+        key: str,
+        summary: str,
+        turn_id: int,
+        store_key: str = "",
+    ) -> None:
+        self.entries.append(ArtifactEntry(
+            kind=kind, key=key, summary=summary, turn_id=turn_id, store_key=store_key,
+        ))
+
+    def get_by_kind(self, kind: str) -> list[ArtifactEntry]:
+        return [e for e in self.entries if e.kind == kind]
+
+    def to_text(self) -> str:
+        """Render as a compact text block for inclusion in context."""
+        if not self.entries:
+            return ""
+        lines = ["[Artifact Index]"]
+        by_kind: dict[str, list[ArtifactEntry]] = {}
+        for e in self.entries:
+            by_kind.setdefault(e.kind, []).append(e)
+        for kind, items in by_kind.items():
+            lines.append(f"  {kind}:")
+            for item in items:
+                lines.append(f"    - {item.key}: {item.summary} (turn {item.turn_id})")
+        return "\n".join(lines)
+
+
+@dataclass
+class StoreEntry:
+    content: str
+    metadata: dict[str, Any]
+    created_at: float
+    ttl_seconds: float
+    access_count: int = 0
+    last_accessed: float = 0.0
+
+    @property
+    def is_expired(self) -> bool:
+        return time.time() > self.created_at + self.ttl_seconds
+
+
+@dataclass
+class CompressionStore:
+    """In-memory store for compressed content retrieval."""
+
+    max_entries: int = 10000
+    default_ttl_seconds: float = 3600
+    adaptive_ttl: bool = True
+    _entries: dict[str, StoreEntry] = field(default_factory=dict)
+    _stats: dict[str, int] = field(default_factory=lambda: {
+        "puts": 0,
+        "gets": 0,
+        "hits": 0,
+        "misses": 0,
+        "evictions": 0,
+    })
+    artifact_index: ArtifactIndex = field(default_factory=ArtifactIndex)
+
+    def put(
+        self,
+        key: str,
+        content: str,
+        metadata: dict[str, Any] | None = None,
+        ttl_seconds: float | None = None,
+    ) -> str:
+        """Store content and return a retrieval key."""
+        # Generate stable key from content hash if not provided
+        store_key = self._make_key(key, content)
+
+        # Evict if at capacity
+        if len(self._entries) >= self.max_entries:
+            self._evict()
+
+        self._entries[store_key] = StoreEntry(
+            content=content,
+            metadata=metadata or {},
+            created_at=time.time(),
+            ttl_seconds=ttl_seconds or self.default_ttl_seconds,
+            last_accessed=time.time(),
+        )
+        self._stats["puts"] += 1
+        return store_key
+
+    def track(
+        self,
+        kind: str,
+        key: str,
+        content: str,
+        turn_id: int = 0,
+        metadata: dict[str, Any] | None = None,
+    ) -> str:
+        """Store content and record it in the artifact index."""
+        summary = content[:80].split("\n")[0] if content else ""
+        store_key = self.put(key, content, metadata)
+        self.artifact_index.add(
+            kind=kind, key=key, summary=summary,
+            turn_id=turn_id, store_key=store_key,
+        )
+        return store_key
+
+    def get(self, key: str) -> str | None:
+        """Retrieve stored content by key."""
+        self._stats["gets"] += 1
+
+        entry = self._entries.get(key)
+        if entry is None:
+            self._stats["misses"] += 1
+            return None
+
+        if entry.is_expired:
+            del self._entries[key]
+            self._stats["misses"] += 1
+            return None
+
+        entry.access_count += 1
+        entry.last_accessed = time.time()
+
+        # Extend TTL on access if adaptive
+        if self.adaptive_ttl:
+            entry.ttl_seconds = min(
+                entry.ttl_seconds * 1.5,
+                self.default_ttl_seconds * 4,
+            )
+
+        self._stats["hits"] += 1
+        return entry.content
+
+    def get_metadata(self, key: str) -> dict[str, Any] | None:
+        """Get metadata for a stored entry."""
+        entry = self._entries.get(key)
+        if entry is None or entry.is_expired:
+            return None
+        return entry.metadata
+
+    def summary(self, key: str, max_length: int = 200) -> str | None:
+        """Get a brief summary of stored content."""
+        content = self.get(key)
+        if content is None:
+            return None
+
+        if len(content) <= max_length:
+            return content
+
+        # Return first and last portions
+        half = max_length // 2
+        return f"{content[:half]}...[{len(content)} chars total]...{content[-half:]}"
+
+    @property
+    def stats(self) -> dict[str, Any]:
+        return {
+            **self._stats,
+            "entries": len(self._entries),
+            "hit_rate": (
+                self._stats["hits"] / self._stats["gets"]
+                if self._stats["gets"] > 0
+                else 0.0
+            ),
+        }
+
+    def clear(self) -> None:
+        """Clear all entries."""
+        self._entries.clear()
+
+    def _make_key(self, key: str, content: str) -> str:
+        """Generate a store key."""
+        content_hash = hashlib.sha256(content.encode()).hexdigest()[:12]
+        return f"{key}:{content_hash}"
+
+    def _evict(self) -> None:
+        """Evict least recently accessed entries."""
+        # Remove expired first
+        expired = [k for k, v in self._entries.items() if v.is_expired]
+        for k in expired:
+            del self._entries[k]
+            self._stats["evictions"] += 1
+
+        # If still over capacity, remove LRU
+        while len(self._entries) >= self.max_entries:
+            lru_key = min(
+                self._entries,
+                key=lambda k: self._entries[k].last_accessed,
+            )
+            del self._entries[lru_key]
+            self._stats["evictions"] += 1

kompact/config.py

@@ -0,0 +1,110 @@
+"""Configuration for Kompact proxy and transforms."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ToonConfig:
+    enabled: bool = True
+    min_array_length: int = 2
+    separator: str = " | "
+
+
+@dataclass
+class ObservationMaskerConfig:
+    enabled: bool = True
+    keep_last_n: int = 3
+    include_summary: bool = True
+
+
+@dataclass
+class CacheAlignerConfig:
+    enabled: bool = True
+    normalize_uuids: bool = True
+    normalize_timestamps: bool = True
+    normalize_paths: bool = True
+
+
+@dataclass
+class JsonCrusherConfig:
+    enabled: bool = True
+    min_array_length: int = 3
+    constant_threshold: float = 1.0  # fraction of items that must match
+    low_cardinality_threshold: int = 5
+
+
+@dataclass
+class SchemaOptimizerConfig:
+    enabled: bool = False  # Requires embedding model, off by default
+    max_tools: int = 10
+    min_relevance_score: float = 0.3
+
+
+@dataclass
+class CodeCompressorConfig:
+    enabled: bool = True
+    keep_signatures: bool = True
+    keep_imports: bool = True
+    keep_docstrings: bool = True
+    keep_type_annotations: bool = True
+    max_body_lines: int = 0  # 0 = remove all bodies
+
+
+@dataclass
+class LogCompressorConfig:
+    enabled: bool = True
+    dedup_threshold: int = 3  # Min consecutive similar lines to compress
+    keep_first_last: bool = True
+
+
+@dataclass
+class ContentCompressorConfig:
+    enabled: bool = True
+    target_ratio: float = 0.5  # Keep 50% of tokens
+    min_tokens_to_compress: int = 200  # Only compress blocks > this
+    entity_boost: float = 1.5
+    position_boost: float = 1.2
+    protect_recent_user_messages: int = 1
+    protect_code_blocks: bool = True
+
+
+@dataclass
+class StoreConfig:
+    max_entries: int = 10000
+    default_ttl_seconds: int = 3600
+    adaptive_ttl: bool = True
+
+
+@dataclass
+class KompactConfig:
+    """Top-level configuration."""
+
+    host: str = "0.0.0.0"
+    port: int = 7878
+    anthropic_base_url: str = "https://api.anthropic.com"
+    openai_base_url: str = "https://api.openai.com"
+    verbose: bool = False
+
+    toon: ToonConfig = field(default_factory=ToonConfig)
+    observation_masker: ObservationMaskerConfig = field(default_factory=ObservationMaskerConfig)
+    cache_aligner: CacheAlignerConfig = field(default_factory=CacheAlignerConfig)
+    json_crusher: JsonCrusherConfig = field(default_factory=JsonCrusherConfig)
+    schema_optimizer: SchemaOptimizerConfig = field(default_factory=SchemaOptimizerConfig)
+    code_compressor: CodeCompressorConfig = field(default_factory=CodeCompressorConfig)
+    log_compressor: LogCompressorConfig = field(default_factory=LogCompressorConfig)
+    content_compressor: ContentCompressorConfig = field(default_factory=ContentCompressorConfig)
+    store: StoreConfig = field(default_factory=StoreConfig)
+
+    @property
+    def disabled_transforms(self) -> set[str]:
+        disabled = set()
+        for name in [
+            "toon", "observation_masker", "cache_aligner",
+            "json_crusher", "schema_optimizer", "code_compressor",
+            "log_compressor", "content_compressor",
+        ]:
+            if not getattr(getattr(self, name), "enabled"):
+                disabled.add(name)
+        return disabled

kompact/metrics/tracker.py

@@ -0,0 +1,138 @@
+"""Metrics tracking for Kompact proxy.
+
+Tracks per-request and cumulative metrics:
+- Tokens before/after per transform
+- Compression ratio
+- Transform latencies
+- Request counts
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any
+
+from kompact.types import PipelineResult
+
+
+@dataclass
+class RequestMetrics:
+    """Metrics for a single request."""
+
+    timestamp: float
+    tokens_before: int
+    tokens_after: int
+    tokens_saved: int
+    compression_ratio: float
+    transform_details: list[dict[str, Any]]
+    latency_ms: float
+    model: str = ""
+    provider: str = ""
+
+
+@dataclass
+class MetricsTracker:
+    """Tracks compression metrics across requests."""
+
+    _requests: list[RequestMetrics] = field(default_factory=list)
+    _max_history: int = 10000
+
+    def record(
+        self,
+        pipeline_result: PipelineResult,
+        tokens_before: int,
+        latency_ms: float,
+    ) -> RequestMetrics:
+        """Record metrics from a pipeline run."""
+        tokens_after = tokens_before - pipeline_result.total_tokens_saved
+
+        metrics = RequestMetrics(
+            timestamp=time.time(),
+            tokens_before=tokens_before,
+            tokens_after=max(0, tokens_after),
+            tokens_saved=pipeline_result.total_tokens_saved,
+            compression_ratio=(
+                tokens_after / tokens_before if tokens_before > 0 else 1.0
+            ),
+            transform_details=[
+                {
+                    "name": r.transform_name,
+                    "tokens_saved": r.tokens_saved,
+                    **r.details,
+                }
+                for r in pipeline_result.transform_results
+            ],
+            latency_ms=latency_ms,
+            model=pipeline_result.request.model,
+            provider=pipeline_result.request.provider.value,
+        )
+
+        self._requests.append(metrics)
+        if len(self._requests) > self._max_history:
+            self._requests = self._requests[-self._max_history:]
+
+        return metrics
+
+    @property
+    def summary(self) -> dict[str, Any]:
+        """Get cumulative summary metrics."""
+        if not self._requests:
+            return {
+                "total_requests": 0,
+                "total_tokens_saved": 0,
+                "total_tokens_processed": 0,
+                "average_compression_ratio": 1.0,
+                "average_latency_ms": 0.0,
+                "transforms": {},
+            }
+
+        total_saved = sum(r.tokens_saved for r in self._requests)
+        total_before = sum(r.tokens_before for r in self._requests)
+        total_after = sum(r.tokens_after for r in self._requests)
+
+        # Per-transform breakdown
+        transform_stats: dict[str, dict[str, Any]] = {}
+        for req in self._requests:
+            for td in req.transform_details:
+                name = td["name"]
+                if name not in transform_stats:
+                    transform_stats[name] = {"tokens_saved": 0, "invocations": 0}
+                transform_stats[name]["tokens_saved"] += td.get("tokens_saved", 0)
+                transform_stats[name]["invocations"] += 1
+
+        return {
+            "total_requests": len(self._requests),
+            "total_tokens_saved": total_saved,
+            "total_tokens_processed": total_before,
+            "total_tokens_output": total_after,
+            "average_compression_ratio": (
+                total_after / total_before if total_before > 0 else 1.0
+            ),
+            "average_latency_ms": (
+                sum(r.latency_ms for r in self._requests) / len(self._requests)
+            ),
+            "transforms": transform_stats,
+        }
+
+    @property
+    def recent(self) -> list[dict[str, Any]]:
+        """Get the last 20 request metrics."""
+        return [
+            {
+                "timestamp": r.timestamp,
+                "tokens_before": r.tokens_before,
+                "tokens_after": r.tokens_after,
+                "tokens_saved": r.tokens_saved,
+                "compression_ratio": round(r.compression_ratio, 3),
+                "latency_ms": round(r.latency_ms, 1),
+                "model": r.model,
+                "provider": r.provider,
+                "transforms": r.transform_details,
+            }
+            for r in self._requests[-20:]
+        ]
+
+    def reset(self) -> None:
+        """Clear all recorded metrics."""
+        self._requests.clear()