clob 0.2.0__py3-none-any.whl

clob/__init__.py

@@ -0,0 +1,5 @@
+"""clob — Universal AI in your terminal."""
+
+__version__ = "0.2.0"
+__author__ = "clob contributors"
+__license__ = "MIT"

clob/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Agent foundations for clob."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from ..providers.base import ChatMessage as ChatMessage
+
+
+class BaseAgent:
+    """Base class for all agents."""
+
+    name: str = "base"
+
+    def __init__(self, runtime) -> None:
+        self.runtime = runtime
+
+    async def run(self, task: str, **kwargs: Any) -> AsyncIterator[str]:
+        raise NotImplementedError

clob/agents/coder.py

@@ -0,0 +1,38 @@
+"""Coding agent — specialized for code generation and editing."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from typing import Any
+
+from . import BaseAgent
+
+
+class CoderAgent(BaseAgent):
+    """Agent specialized for code generation and editing tasks."""
+
+    name = "coder"
+
+    SYSTEM_PROMPT = """You are an expert software engineer.
+When asked to write code:
+1. Always wrap code in markdown fences with the language tag
+2. Explain what the code does
+3. Mention any dependencies
+4. Follow best practices for the language
+"""
+
+    async def run(self, task: str, **kwargs: Any) -> AsyncIterator[str]:
+        from ..providers.base import ChatMessage
+
+        provider = self.runtime.registry.get(self.runtime.provider)
+        if not provider:
+            yield "No provider configured."
+            return
+
+        messages = [
+            ChatMessage(role="system", content=self.SYSTEM_PROMPT),
+            ChatMessage(role="user", content=task),
+        ]
+        async for chunk in provider.stream_chat(messages, model=self.runtime.model, **kwargs):
+            if chunk.delta:
+                yield chunk.delta

clob/analytics/__init__.py

@@ -0,0 +1,150 @@
+"""Token and cost analytics for clob.
+
+Tracks:
+- Input/output tokens per session
+- Estimated cost based on provider pricing
+- Daily/session usage summaries
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+
+# ── Provider pricing (per 1M tokens, USD) ─────────────────────
+
+PRICING: dict[str, dict[str, float]] = {
+    # provider -> model_prefix -> (input, output) per 1M tokens
+    "openrouter": {
+        "default": (0.50, 1.50),
+        "openai/gpt-4o": (2.50, 10.00),
+        "openai/gpt-4o-mini": (0.15, 0.60),
+        "anthropic/claude": (3.00, 15.00),
+        "meta-llama": (0.05, 0.05),
+    },
+    "groq": {
+        "default": (0.05, 0.10),
+        "llama3-70b": (0.59, 0.79),
+        "llama3-8b": (0.05, 0.08),
+        "mixtral": (0.24, 0.24),
+    },
+    "ollama": {
+        "default": (0.0, 0.0),  # local, free
+    },
+    "nvidia": {
+        "default": (0.20, 0.20),
+    },
+}
+
+
+def _estimate_cost(provider: str, model: str, in_tokens: int, out_tokens: int) -> float:
+    """Estimate USD cost for a completion."""
+    provider_prices = PRICING.get(provider, PRICING.get("openrouter", {}))
+
+    # Find best matching model prefix
+    in_price, out_price = provider_prices.get("default", (0.50, 1.50))
+    for prefix, prices in provider_prices.items():
+        if prefix != "default" and model.startswith(prefix):
+            in_price, out_price = prices
+            break
+
+    return (in_tokens * in_price + out_tokens * out_price) / 1_000_000
+
+
+@dataclass
+class TurnStats:
+    """Stats for a single request/response turn."""
+
+    provider: str
+    model: str
+    input_tokens: int
+    output_tokens: int
+    latency_ms: float
+    timestamp: datetime = field(default_factory=lambda: __import__("datetime").datetime.now())
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+    @property
+    def estimated_cost_usd(self) -> float:
+        return _estimate_cost(self.provider, self.model, self.input_tokens, self.output_tokens)
+
+
+@dataclass
+class SessionStats:
+    """Aggregated stats for a session."""
+
+    session_id: int
+    turns: list[TurnStats] = field(default_factory=list)
+
+    def record(self, turn: TurnStats) -> None:
+        self.turns.append(turn)
+
+    @property
+    def total_input_tokens(self) -> int:
+        return sum(t.input_tokens for t in self.turns)
+
+    @property
+    def total_output_tokens(self) -> int:
+        return sum(t.output_tokens for t in self.turns)
+
+    @property
+    def total_tokens(self) -> int:
+        return self.total_input_tokens + self.total_output_tokens
+
+    @property
+    def total_cost_usd(self) -> float:
+        return sum(t.estimated_cost_usd for t in self.turns)
+
+    @property
+    def turn_count(self) -> int:
+        return len(self.turns)
+
+    def summary_line(self) -> str:
+        """One-line summary for status bar."""
+        cost = self.total_cost_usd
+        cost_str = f"${cost:.4f}" if cost > 0 else "free"
+        return f"↑{self.total_input_tokens} ↓{self.total_output_tokens} {cost_str}"
+
+
+class AnalyticsTracker:
+    """Runtime analytics tracker — in-memory for current session."""
+
+    def __init__(self) -> None:
+        self._sessions: dict[int, SessionStats] = {}
+        self._global_turns: list[TurnStats] = []
+
+    def record(self, session_id: int, turn: TurnStats) -> None:
+        if session_id not in self._sessions:
+            self._sessions[session_id] = SessionStats(session_id=session_id)
+        self._sessions[session_id].record(turn)
+        self._global_turns.append(turn)
+
+    def get_session(self, session_id: int) -> SessionStats | None:
+        return self._sessions.get(session_id)
+
+    def global_summary(self) -> dict:
+        total_in = sum(t.input_tokens for t in self._global_turns)
+        total_out = sum(t.output_tokens for t in self._global_turns)
+        total_cost = sum(t.estimated_cost_usd for t in self._global_turns)
+        return {
+            "total_input_tokens": total_in,
+            "total_output_tokens": total_out,
+            "total_tokens": total_in + total_out,
+            "total_cost_usd": total_cost,
+            "turn_count": len(self._global_turns),
+        }
+
+    def format_usage_report(self) -> str:
+        g = self.global_summary()
+        lines = [
+            "── clob Usage Report ────────────────────────",
+            f"  Total turns:    {g['turn_count']}",
+            f"  Input tokens:   {g['total_input_tokens']:,}",
+            f"  Output tokens:  {g['total_output_tokens']:,}",
+            f"  Total tokens:   {g['total_tokens']:,}",
+            f"  Est. cost:      ${g['total_cost_usd']:.4f} USD",
+            "─────────────────────────────────────────────",
+        ]
+        return "\n".join(lines)

clob/attachments/__init__.py

@@ -0,0 +1,123 @@
+"""Multimodal attachment handling for clob.
+
+Supports: images, PDFs, text files, code files.
+Converts to provider-compatible message formats.
+"""
+
+from __future__ import annotations
+
+import base64
+import mimetypes
+from dataclasses import dataclass
+from pathlib import Path
+
+SUPPORTED_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".gif", ".webp"}
+SUPPORTED_TEXT_EXTS = {
+    ".txt",
+    ".md",
+    ".py",
+    ".js",
+    ".ts",
+    ".go",
+    ".rs",
+    ".java",
+    ".c",
+    ".cpp",
+    ".h",
+    ".css",
+    ".html",
+    ".json",
+    ".yaml",
+    ".yml",
+    ".toml",
+    ".sh",
+    ".sql",
+    ".xml",
+}
+
+
+@dataclass
+class Attachment:
+    path: Path
+    mime_type: str
+    data: bytes
+    filename: str
+
+    @property
+    def is_image(self) -> bool:
+        return self.mime_type.startswith("image/")
+
+    @property
+    def is_text(self) -> bool:
+        return self.mime_type.startswith("text/") or self.path.suffix in SUPPORTED_TEXT_EXTS
+
+    @property
+    def is_pdf(self) -> bool:
+        return self.mime_type == "application/pdf"
+
+    def to_base64(self) -> str:
+        return base64.standard_b64encode(self.data).decode()
+
+    def to_openai_content_part(self) -> dict:
+        """Convert to OpenAI-compatible vision content part."""
+        if self.is_image:
+            return {
+                "type": "image_url",
+                "image_url": {"url": f"data:{self.mime_type};base64,{self.to_base64()}"},
+            }
+        elif self.is_text:
+            try:
+                text = self.data.decode(errors="replace")
+            except Exception:
+                text = f"[Binary file: {self.filename}]"
+            return {"type": "text", "text": f"```\n# {self.filename}\n{text}\n```"}
+        else:
+            return {"type": "text", "text": f"[Attached file: {self.filename} ({self.mime_type})]"}
+
+    def preview(self, max_chars: int = 200) -> str:
+        if self.is_image:
+            return f"🖼 {self.filename} ({len(self.data) // 1024}KB image)"
+        if self.is_text:
+            try:
+                text = self.data.decode(errors="replace")[:max_chars]
+                return f"📄 {self.filename}\n{text}..."
+            except Exception:
+                pass
+        return f"📎 {self.filename} ({self.mime_type})"
+
+
+def load_attachment(path: Path) -> Attachment:
+    """Load a file as an Attachment."""
+    mime, _ = mimetypes.guess_type(str(path))
+    if mime is None:
+        # Fallback detection
+        if path.suffix in SUPPORTED_IMAGE_EXTS:
+            mime = f"image/{path.suffix.lstrip('.')}"
+        elif path.suffix in SUPPORTED_TEXT_EXTS:
+            mime = "text/plain"
+        else:
+            mime = "application/octet-stream"
+
+    return Attachment(
+        path=path,
+        mime_type=mime,
+        data=path.read_bytes(),
+        filename=path.name,
+    )
+
+
+def attachments_to_messages(
+    text: str,
+    attachments: list[Attachment],
+) -> list[dict]:
+    """Build OpenAI-compatible content list from text + attachments."""
+    if not attachments:
+        return [{"role": "user", "content": text}]
+
+    content = []
+    # Add attachments first
+    for att in attachments:
+        content.append(att.to_openai_content_part())
+    # Then the text
+    content.append({"type": "text", "text": text})
+    return [{"role": "user", "content": content}]

clob/config/__init__.py

@@ -0,0 +1,3 @@
+from .settings import CONFIG_DIR, CONFIG_FILE, DB_FILE, AppConfig, DefaultConfig, ProviderConfig
+
+__all__ = ["AppConfig", "ProviderConfig", "DefaultConfig", "CONFIG_DIR", "CONFIG_FILE", "DB_FILE"]

clob/config/settings.py

@@ -0,0 +1,162 @@
+"""Configuration models and settings for clob."""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, field_validator
+
+CONFIG_DIR = Path.home() / ".config" / "clob"
+CONFIG_FILE = CONFIG_DIR / "config.toml"
+DB_FILE = CONFIG_DIR / "clob.db"
+
+
+class ProviderConfig(BaseModel):
+    """Configuration for a single provider."""
+
+    name: str = ""
+    base_url: str = ""
+    api_key: str = ""
+    chat_endpoint: str = "/chat/completions"
+    models_endpoint: str = "/models"
+    images_endpoint: str = "/images/generations"
+    embeddings_endpoint: str = "/embeddings"
+    extra_headers: dict[str, str] = Field(default_factory=dict)
+    timeout: float = 60.0
+    enabled: bool = True
+
+    @field_validator("api_key", mode="before")
+    @classmethod
+    def resolve_env(cls, v: str) -> str:
+        """Resolve env:VAR_NAME references."""
+        if isinstance(v, str) and v.startswith("env:"):
+            env_var = v[4:]
+            return os.environ.get(env_var, "")
+        return v or ""
+
+
+class DefaultConfig(BaseModel):
+    """Default provider/model selection."""
+
+    provider: str = "openrouter"
+    model: str = "openai/gpt-4o-mini"
+    stream: bool = True
+    max_tokens: int = 4096
+    temperature: float = 0.7
+    system_prompt: str = "You are a helpful AI assistant."
+    theme: str = "dark"
+
+
+class AppConfig(BaseModel):
+    """Full application configuration."""
+
+    default: DefaultConfig = Field(default_factory=DefaultConfig)
+    providers: dict[str, ProviderConfig] = Field(default_factory=dict)
+    profiles: dict[str, Any] = Field(default_factory=dict)
+
+    @classmethod
+    def load(cls) -> AppConfig:
+        if not CONFIG_FILE.exists():
+            return cls._create_defaults()
+        with open(CONFIG_FILE, "rb") as f:
+            data = tomllib.load(f)
+        return cls._from_dict(data)
+
+    @classmethod
+    def _from_dict(cls, data: dict[str, Any]) -> AppConfig:
+        default = DefaultConfig(**data.get("default", {}))
+        providers: dict[str, ProviderConfig] = {}
+        for name, pdata in data.get("providers", {}).items():
+            providers[name] = ProviderConfig(name=name, **pdata)
+        profiles = data.get("profiles", {})
+        return cls(default=default, providers=providers, profiles=profiles)
+
+    def apply_profile(self, name: str) -> bool:
+        p = self.profiles.get(name)
+        if not p:
+            return False
+        if p.get("provider"):
+            self.default.provider = p["provider"]
+        if p.get("model"):
+            self.default.model = p["model"]
+        if p.get("system_prompt"):
+            self.default.system_prompt = p["system_prompt"]
+        if p.get("temperature") is not None:
+            self.default.temperature = p["temperature"]
+        if p.get("max_tokens") is not None:
+            self.default.max_tokens = p["max_tokens"]
+        return True
+
+    @classmethod
+    def _create_defaults(cls) -> AppConfig:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        config = cls()
+        config.providers = {
+            "openrouter": ProviderConfig(
+                name="openrouter",
+                base_url="https://openrouter.ai/api/v1",
+                api_key="env:OPENROUTER_API_KEY",
+            ),
+            "groq": ProviderConfig(
+                name="groq",
+                base_url="https://api.groq.com/openai/v1",
+                api_key="env:GROQ_API_KEY",
+            ),
+            "ollama": ProviderConfig(
+                name="ollama",
+                base_url="http://localhost:11434",
+                api_key="",
+                chat_endpoint="/api/chat",
+                models_endpoint="/api/tags",
+            ),
+            "nvidia": ProviderConfig(
+                name="nvidia",
+                base_url="https://integrate.api.nvidia.com/v1",
+                api_key="env:NVIDIA_API_KEY",
+            ),
+        }
+        _write_default_config(config)
+        return config
+
+    def get_provider(self, name: str) -> ProviderConfig | None:
+        return self.providers.get(name)
+
+    def save(self) -> None:
+        CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+        _write_default_config(self)
+
+
+def _write_default_config(config: AppConfig) -> None:
+    """Write a default config.toml."""
+    lines = [
+        "# clob configuration\n",
+        "# https://github.com/crishacks/clob\n\n",
+        "[default]\n",
+        f'provider = "{config.default.provider}"\n',
+        f'model = "{config.default.model}"\n',
+        f"stream = {str(config.default.stream).lower()}\n",
+        f"max_tokens = {config.default.max_tokens}\n",
+        f"temperature = {config.default.temperature}\n",
+        f'theme = "{config.default.theme}"\n\n',
+    ]
+    for pname, pconf in config.providers.items():
+        lines.append(f"[providers.{pname}]\n")
+        lines.append(f'base_url = "{pconf.base_url}"\n')
+        # Don't write resolved keys back — keep env: refs
+        lines.append(f'api_key = "env:{pname.upper()}_API_KEY"\n\n')
+
+    with open(CONFIG_FILE, "w") as f:
+        f.writelines(lines)
+
+
+class ProfileConfig(BaseModel):
+    """A named configuration profile (work, local, etc.)."""
+
+    provider: str = ""
+    model: str = ""
+    system_prompt: str = ""
+    temperature: float | None = None
+    max_tokens: int | None = None

clob/core/__init__.py

@@ -0,0 +1,3 @@
+from .runtime import Runtime
+
+__all__ = ["Runtime"]

clob/core/runtime.py

@@ -0,0 +1,173 @@
+"""Core runtime v0.2.0 — wires providers, memory, analytics, workspace."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Any
+
+from ..analytics import AnalyticsTracker, TurnStats
+from ..config.settings import AppConfig
+from ..memory.manager import MemoryManager
+from ..providers.base import ChatChunk, ChatMessage
+from ..providers.capabilities import ProviderCapabilities, get_capabilities
+from ..providers.registry import ProviderRegistry
+from ..workspace import resolve_context_refs
+
+
+class Runtime:
+    """
+    Central runtime v0.2.0:
+    - Provider selection + capability awareness
+    - Streaming with token counting
+    - Analytics tracking
+    - Workspace context injection (@file, @dir, @workspace)
+    - Session management
+    """
+
+    def __init__(self, config: AppConfig) -> None:
+        self.config = config
+        self.registry = ProviderRegistry()
+        self.memory = MemoryManager()
+        self.analytics = AnalyticsTracker()
+        self._current_session_id: int | None = None
+        self._current_provider: str = config.default.provider
+        self._current_model: str = config.default.model
+        self._workspace_root: Path = Path.cwd()
+
+    async def start(self) -> None:
+        self.registry.load_from_config(self.config)
+        await self.memory.start()
+
+    async def stop(self) -> None:
+        await self.registry.close_all()
+        await self.memory.stop()
+
+    @property
+    def provider(self) -> str:
+        return self._current_provider
+
+    @property
+    def model(self) -> str:
+        return self._current_model
+
+    @property
+    def capabilities(self) -> ProviderCapabilities:
+        return get_capabilities(self._current_provider)
+
+    def set_provider(self, name: str) -> bool:
+        if self.registry.get(name):
+            self._current_provider = name
+            return True
+        return False
+
+    def set_model(self, model: str) -> None:
+        self._current_model = model
+
+    def set_workspace(self, path: Path) -> None:
+        self._workspace_root = path.resolve()
+
+    async def ensure_session(self) -> int:
+        if self._current_session_id is None:
+            session = await self.memory.new_session(
+                provider=self._current_provider,
+                model=self._current_model,
+            )
+            self._current_session_id = session.id
+        return self._current_session_id
+
+    async def new_session(self) -> int:
+        session = await self.memory.new_session(
+            provider=self._current_provider,
+            model=self._current_model,
+        )
+        self._current_session_id = session.id
+        return session.id
+
+    async def load_session(self, session_id: int) -> bool:
+        session = await self.memory.get_session(session_id)
+        if session:
+            self._current_session_id = session_id
+            if session.provider:
+                self._current_provider = session.provider
+            if session.model:
+                self._current_model = session.model
+            return True
+        return False
+
+    async def _resolve_input(self, user_input: str) -> str:
+        if any(ref in user_input for ref in ("@file", "@dir", "@workspace")):
+            return resolve_context_refs(user_input, self._workspace_root)
+        return user_input
+
+    async def _build_messages(self, session_id: int) -> list[ChatMessage]:
+        messages: list[ChatMessage] = []
+        system = self.config.default.system_prompt
+        if system:
+            messages.append(ChatMessage(role="system", content=system))
+        history = await self.memory.get_history(session_id)
+        for msg in history:
+            messages.append(ChatMessage(role=msg.role, content=msg.content))
+        return messages
+
+    async def stream_response(self, user_input: str, **kwargs: Any) -> AsyncIterator[ChatChunk]:
+        provider = self.registry.get(self._current_provider)
+        if not provider:
+            raise RuntimeError(
+                f"Provider '{self._current_provider}' not configured. "
+                "Run 'clob doctor' to check setup."
+            )
+
+        await self._resolve_input(user_input)
+        session_id = await self.ensure_session()
+        await self.memory.add_message(session_id, "user", user_input)
+
+        messages = await self._build_messages(session_id)
+
+        t0 = time.monotonic()
+        full_response = ""
+        input_tokens = sum(len(m.content.split()) for m in messages)
+
+        async for chunk in provider.stream_chat(
+            messages,
+            model=self._current_model,
+            max_tokens=self.config.default.max_tokens,
+            temperature=self.config.default.temperature,
+            **kwargs,
+        ):
+            full_response += chunk.delta
+            yield chunk
+
+        latency_ms = (time.monotonic() - t0) * 1000
+        output_tokens = len(full_response.split())
+
+        await self.memory.add_message(session_id, "assistant", full_response)
+
+        self.analytics.record(
+            session_id,
+            TurnStats(
+                provider=self._current_provider,
+                model=self._current_model,
+                input_tokens=input_tokens,
+                output_tokens=output_tokens,
+                latency_ms=latency_ms,
+            ),
+        )
+
+        history = await self.memory.get_history(session_id)
+        if len(history) == 2:
+            title = user_input[:50].strip()
+            await self.memory.rename_session(session_id, title)
+
+    async def chat(self, user_input: str, **kwargs: Any) -> str:
+        result = ""
+        async for chunk in self.stream_response(user_input, **kwargs):
+            result += chunk.delta
+        return result
+
+    def session_stats_line(self) -> str:
+        if self._current_session_id is None:
+            return ""
+        stats = self.analytics.get_session(self._current_session_id)
+        return stats.summary_line() if stats else ""