clob 0.2.0__tar.gz

clob-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main, dev]
+  pull_request:
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install ruff black
+      - run: ruff check clob/
+      - run: black --check clob/
+
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python: ["3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v

clob-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,175 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  packages: write
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install -e ".[dev]"
+      - run: pytest tests/ -v
+
+  build-wheel:
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install build hatchling
+      - run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  build-binaries:
+    needs: test
+
+    strategy:
+      matrix:
+        include:
+          - os: ubuntu-latest
+            artifact: clob-linux-x64
+            ext: ""
+
+          - os: macos-latest
+            artifact: clob-macos-x64
+            ext: ""
+
+          - os: windows-latest
+            artifact: clob-windows-x64
+            ext: ".exe"
+
+    runs-on: ${{ matrix.os }}
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - run: pip install -e . pyinstaller
+
+      - name: Build binary
+        run: |
+          pyinstaller --onefile --name clob${{ matrix.ext }} \
+            --hidden-import clob \
+            clob/main.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ matrix.artifact }}
+          path: dist/clob*
+
+  docker:
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - uses: docker/build-push-action@v5
+        with:
+          context: .
+          push: true
+          tags: |
+            ghcr.io/crishacks/clob:latest
+            ghcr.io/crishacks/clob:${{ github.ref_name }}
+
+  pypi:
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: build-wheel
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Verify distributions
+        run: ls -la dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: [build-wheel, build-binaries, docker]
+
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts/
+
+      - name: Collect release assets
+        run: |
+          mkdir release-assets
+          find artifacts/ -type f | xargs -I{} cp {} release-assets/
+          ls -la release-assets/
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: release-assets/*
+          generate_release_notes: true
+          body_path: CHANGELOG.md
+
+  homebrew-bump:
+    needs: github-release
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Compute tarball SHA256
+        id: sha
+        run: |
+          URL="https://github.com/crishacks/clob/archive/refs/tags/${{ github.ref_name }}.tar.gz"
+          SHA=$(curl -sL "$URL" | shasum -a 256 | cut -d' ' -f1)
+          echo "sha256=$SHA" >> $GITHUB_OUTPUT
+
+      - name: Update Homebrew tap
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.TAP_GITHUB_TOKEN }}
+          repository: crishacks/homebrew-tap
+          event-type: bump-clob
+          client-payload: |
+            {
+              "version": "${{ github.ref_name }}",
+              "sha256": "${{ steps.sha.outputs.sha256 }}"
+            }

clob-0.2.0/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+venv/
+env/
+.env
+*.log
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+node_modules/
+*.tar.gz
+*.whl

clob-0.2.0/AGENTS.md

@@ -0,0 +1,237 @@
+# Agent Architecture
+
+clob includes a foundational agent system designed for extensibility toward autonomous AI coding and multi-step workflows.
+
+---
+
+## Overview
+
+Agents are specialized AI workflows that go beyond single-turn chat. They can:
+
+- Plan multi-step tasks
+- Execute tools (shell, filesystem, git)
+- Generate and apply code patches
+- Chain multiple AI calls
+- Maintain execution context across steps
+
+---
+
+## Current Agents
+
+### BaseAgent
+
+All agents inherit from `BaseAgent`:
+
+```python
+class BaseAgent:
+    name: str = "base"
+
+    def __init__(self, runtime) -> None:
+        self.runtime = runtime
+
+    async def run(self, task: str, **kwargs) -> AsyncIterator[str]:
+        raise NotImplementedError
+```
+
+### CoderAgent
+
+Specialized for code generation and editing.
+
+```python
+from clob.agents.coder import CoderAgent
+
+agent = CoderAgent(runtime)
+async for token in agent.run("Write a Python quicksort implementation"):
+    print(token, end="", flush=True)
+```
+
+The coder agent uses a specialized system prompt that:
+- Always wraps code in markdown fences with language tags
+- Explains what the code does
+- Lists dependencies
+- Follows language best practices
+
+---
+
+## Planned Agents (Roadmap)
+
+### PlannerAgent
+
+Breaks complex tasks into subtasks:
+
+```
+Task: "Refactor this module to use async/await"
+→ Step 1: Analyze existing code
+→ Step 2: Identify blocking calls
+→ Step 3: Generate async version
+→ Step 4: Write tests
+→ Step 5: Verify changes
+```
+
+### ExecutorAgent
+
+Executes plans step-by-step with tool calls:
+
+```python
+# Planned API
+async for step in executor.run(plan):
+    print(f"[{step.status}] {step.description}")
+    if step.requires_approval:
+        approved = await confirm(step.command)
+```
+
+### GitAgent
+
+Understands git context:
+- Reads current diff
+- Understands commit history
+- Generates commit messages
+- Creates branches for changes
+
+---
+
+## Tool System
+
+Agents use tools to interact with the environment:
+
+### Available Tools
+
+| Tool | Module | Description |
+|------|--------|-------------|
+| Shell | `clob.tools.shell` | Execute shell commands (sandboxed) |
+| Filesystem | `clob.tools.filesystem` | Read/write files |
+| Git | `clob.tools.git_tools` | Git operations |
+| Python Exec | `clob.tools.python_exec` | Execute Python snippets |
+
+### Using Tools in Agents
+
+```python
+from clob.sandbox import Sandbox, PermissionLevel
+from clob.tools.shell import run_shell
+
+class MyAgent(BaseAgent):
+    async def run(self, task: str, **kwargs):
+        sandbox = Sandbox(permission=PermissionLevel.RESTRICTED)
+        
+        # Run a safe command
+        result = await sandbox.run("git diff --stat")
+        context = f"Current git diff:\n{result.stdout}"
+        
+        # Send context + task to AI
+        async for chunk in self.runtime.stream_response(f"{context}\n\n{task}"):
+            if chunk.delta:
+                yield chunk.delta
+```
+
+---
+
+## Sandbox Permissions
+
+Agents must specify a permission level for tool execution:
+
+| Level | Allowed Commands | Use Case |
+|-------|-----------------|----------|
+| `SAFE` | Read-only: ls, cat, git status, grep | Exploration agents |
+| `RESTRICTED` | Dev tools: pytest, pip, make, git | Coding agents |
+| `FULL` | All commands | Advanced agents (requires explicit consent) |
+
+```python
+from clob.sandbox import Sandbox, PermissionLevel
+
+# Default: safe
+sandbox = Sandbox()
+
+# Coding agent: restricted
+sandbox = Sandbox(permission=PermissionLevel.RESTRICTED)
+
+# Full access: user must explicitly enable
+sandbox = Sandbox(permission=PermissionLevel.FULL)
+```
+
+---
+
+## Writing a Custom Agent
+
+```python
+from clob.agents import BaseAgent
+from clob.sandbox import Sandbox, PermissionLevel
+from typing import AsyncIterator
+
+class ReviewAgent(BaseAgent):
+    """Code review agent — reads files and provides feedback."""
+    
+    name = "reviewer"
+    
+    SYSTEM_PROMPT = """You are an expert code reviewer.
+Analyze code for: correctness, style, performance, security.
+Be specific and actionable in your feedback.
+"""
+
+    async def run(self, task: str, **kwargs) -> AsyncIterator[str]:
+        from clob.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
+```
+
+---
+
+## MCP-Ready Design
+
+The agent and tool system is architected to support future MCP (Model Context Protocol) integration:
+
+```python
+# Future: MCP tool registration (not yet implemented)
+class ToolRegistry:
+    """Abstract registry — will support MCP servers."""
+    
+    def register(self, tool: BaseTool) -> None: ...
+    def register_mcp_server(self, url: str) -> None: ...  # future
+    async def call(self, name: str, **kwargs) -> Any: ...
+```
+
+When MCP support is added, agents will be able to use external MCP servers as tool providers without code changes.
+
+---
+
+## Agent Configuration
+
+Agents can be configured via the runtime:
+
+```python
+runtime.set_provider("openrouter")
+runtime.set_model("anthropic/claude-sonnet-4")
+
+agent = CoderAgent(runtime)
+```
+
+Or via environment:
+
+```bash
+CLOB_PROVIDER=groq CLOB_MODEL=llama3-70b-8192 clob chat "write a sorting algorithm"
+```
+
+---
+
+## Roadmap
+
+- [ ] PlannerAgent with multi-step task decomposition
+- [ ] ExecutorAgent with step-by-step approval flow
+- [ ] GitAgent with commit/branch awareness
+- [ ] Multi-agent coordination
+- [ ] Agent memory persistence
+- [ ] MCP server integration
+- [ ] Agent marketplace / plugin agents

clob-0.2.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+# Changelog
+
+All notable changes to clob are documented here.
+
+This project adheres to [Semantic Versioning](https://semver.org/) and [Conventional Commits](https://www.conventionalcommits.org/).
+
+---
+
+## [Unreleased]
+
+### Planned
+- MCP (Model Context Protocol) support
+- Anthropic Claude native provider
+- Voice input support
+- Multi-agent workflows
+- VS Code extension
+- Web UI companion
+
+---
+
+## [0.2.0] — 2026-05-16
+
+### Added
+
+#### Core
+- **Provider capability system** — `ProviderCapabilities` dataclass with per-provider feature flags (vision, tools, embeddings, json_mode, image generation, audio, streaming)
+- **Analytics tracker** — per-session token counting, estimated cost by provider/model, usage reports
+- **Workspace context** — `@file path.py`, `@dir src/`, `@workspace` reference injection into AI prompts
+- **Workspace indexer** — full project file indexer with language breakdown, token budgeting, `.clobignore` support
+- **Config profiles** — named profiles (`[profiles.work]`, `[profiles.local]`) for quick provider/model switching
+
+#### TUI
+- **Command palette** — `Ctrl+P` fuzzy command launcher with all app actions
+- **Usage analytics screen** — `Ctrl+U` shows token/cost report
+- **Memory search screen** — `Ctrl+F` searches conversation history
+- **Session export** — export current session as Markdown
+- **Sidebar toggle** — `Ctrl+B` shows/hides sidebar
+- **Capability badges** — provider capabilities shown in TUI header
+- **Live stats in status bar** — token counts and estimated cost update as you chat
+- **Improved streaming renderer** — code-fence detection, throttled re-renders, cancel support, reduced flicker
+
+#### Rendering
+- **Terminal image renderer** — auto-detects Kitty / iTerm2 / Sixel / ASCII fallback
+- **`ImageRenderer` class** — protocol-aware rendering with graceful degradation
+
+#### Security & Execution
+- **Sandbox system** — `SAFE / RESTRICTED / FULL` permission levels with execution log
+- **Restricted allowlists** — safe commands only by default
+
+#### Themes
+- **Theme system** — 4 built-in themes: dark, light, cyberpunk, nord
+- **User themes** — place `.tcss` files in `~/.config/clob/themes/`
+- `clob theme list` and `clob theme set <name>` CLI commands
+
+#### Attachments
+- **Multimodal attachments** — image, text, code, PDF loading with OpenAI content-part format
+- Attachment preview in TUI
+
+#### CLI
+- `clob workspace index` / `stats` / `context`
+- `clob session export` / `delete`
+- `clob plugins list` / `install`
+- `clob theme list` / `set`
+- `clob usage`
+
+### Changed
+- Runtime upgraded with analytics, workspace context injection, and capability awareness
+- Status bar now shows token stats and capability badges
+- Welcome screen shows provider capabilities on startup
+- All repo references updated to `crishacks/clob`
+
+### Fixed
+- Code fence detection during streaming (no more broken partial fences)
+- Streaming widget render throttled to reduce flicker
+- Config `_from_dict` now correctly parses profiles block
+
+---
+
+## [0.1.0] — 2026-05-15
+
+### Added
+
+#### Core
+- **Textual TUI** — full terminal user interface with sidebar, chat window, streaming output
+- **Runtime** — central async runtime wiring providers, memory, and streaming
+- **Streaming** — token-by-token async streaming with `async for chunk in provider.stream_chat(...)`
+
+#### Providers
+- **OpenRouter** — access to hundreds of models via one API
+- **Groq** — ultra-fast inference
+- **NVIDIA Build** — NVIDIA-hosted models
+- **Ollama** — local model support with model pulling
+- **Generic OpenAI-compatible** — any OpenAI-compatible endpoint via config
+
+#### Provider System
+- `BaseProvider` abstract class with `chat`, `stream_chat`, `list_models`, `generate_image`, `embeddings`
+- `ProviderRegistry` — central provider management
+- Custom provider config via `[providers.my-provider]` in `config.toml`
+
+#### Memory
+- **SQLite persistence** — sessions, messages, search via `aiosqlite`
+- `sessions`, `messages`, `memories` database tables
+- Full-text message search
+
+#### CLI
+- `clob` — launch TUI
+- `clob chat` — single message non-TUI mode
+- `clob models` — list available models
+- `clob providers` — list configured providers
+- `clob config` — show/edit configuration
+- `clob memory` — search history, list sessions
+- `clob ollama` — list and pull local models
+- `clob doctor` — installation diagnostics
+
+#### Configuration
+- `~/.config/clob/config.toml` — TOML configuration
+- Environment variable resolution (`env:VAR_NAME`)
+- Auto-generated default config on first run
+
+#### Developer
+- Full `pyproject.toml` with hatchling build
+- Ruff + Black code quality tooling
+- pytest + pytest-asyncio test suite (11 tests)
+- MIT License
+- Dockerfile + docker-compose.yml
+- GitHub Actions CI (Linux, macOS, Windows) and Release workflows
+- Plugin loader system
+
+---
+
+## Version History
+
+| Version | Date | Highlights |
+|---------|------|-----------|
+| 0.2.0 | 2026-05-16 | Analytics, workspace context, command palette, themes, sandbox |
+| 0.1.0 | 2026-05-15 | Initial release — TUI, streaming, 5 providers, SQLite memory |
+
+---
+
+[Unreleased]: https://github.com/crishacks/clob/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/crishacks/clob/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/crishacks/clob/releases/tag/v0.1.0