repobrief 0.1.1__py3-none-any.whl

repobrief/__init__.py

@@ -0,0 +1,3 @@
+"""RepoBrief — Pack any repo into clean LLM context, then chat with it."""
+
+__version__ = "0.1.1"

repobrief/backends/base.py

@@ -0,0 +1,70 @@
+"""Abstract base class for LLM backends.
+
+All backends (cloud, Ollama, future local runtimes) must implement this interface.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Iterator
+from dataclasses import dataclass
+
+
+@dataclass
+class ChatMessage:
+    """A single message in a conversation.
+
+    Attributes:
+        role: 'user', 'assistant', or 'system'.
+        content: The message text.
+    """
+
+    role: str  # "user" | "assistant" | "system"
+    content: str
+
+
+class LLMBackend(ABC):
+    """Abstract interface for LLM backends.
+
+    Implementing classes must provide:
+    - generate(): Send a prompt and stream back response tokens
+    - validate(): Check that the backend is properly configured and reachable
+    """
+
+    @abstractmethod
+    def generate(
+        self,
+        system_prompt: str,
+        user_message: str,
+        history: list[ChatMessage] | None = None,
+    ) -> Iterator[str]:
+        """Send a prompt and yield response tokens as they stream in.
+
+        Args:
+            system_prompt: System-level instructions (includes the repo digest).
+            user_message: The user's question.
+            history: Previous conversation messages (for REPL mode).
+
+        Yields:
+            String chunks of the response as they arrive.
+
+        Raises:
+            ConnectionError: If the backend is unreachable.
+            PermissionError: If authentication fails (bad API key).
+            RuntimeError: For other backend errors.
+        """
+
+    @abstractmethod
+    def validate(self) -> tuple[bool, str]:
+        """Check if the backend is properly configured and reachable.
+
+        Returns:
+            Tuple of (is_valid, message).
+            - (True, "Ready") if everything is configured.
+            - (False, "Missing API key...") if there's a problem.
+        """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Human-readable name of this backend (e.g., 'Anthropic Claude')."""

repobrief/backends/cloud.py

@@ -0,0 +1,227 @@
+"""Cloud LLM backend -- supports Anthropic (Claude) and OpenAI (GPT) APIs.
+
+Determines which provider to use based on the model name:
+- Models starting with 'claude' -> Anthropic API
+- Models starting with 'gpt' or 'o1' -> OpenAI API
+- Explicit provider prefix: 'anthropic:model-name' or 'openai:model-name'
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterator
+
+from repobrief.backends.base import ChatMessage, LLMBackend
+
+# -- Provider Detection --------------------------------------------------------
+
+
+def _detect_provider(model: str) -> str:
+    """Detect the API provider from the model name.
+
+    Args:
+        model: Model name string.
+
+    Returns:
+        'anthropic' or 'openai'.
+
+    Raises:
+        ValueError: If the provider cannot be determined.
+    """
+    model_lower = model.lower()
+
+    # Explicit prefix
+    if model_lower.startswith("anthropic:"):
+        return "anthropic"
+    if model_lower.startswith("openai:"):
+        return "openai"
+
+    # Infer from model name
+    if model_lower.startswith("claude"):
+        return "anthropic"
+    if model_lower.startswith(("gpt", "o1", "o3")):
+        return "openai"
+
+    raise ValueError(
+        f"Cannot determine provider for model '{model}'. "
+        f"Use a prefix: 'anthropic:{model}' or 'openai:{model}'"
+    )
+
+
+def _strip_provider_prefix(model: str) -> str:
+    """Remove the provider prefix from a model name."""
+    if ":" in model:
+        return model.split(":", 1)[1]
+    return model
+
+
+class CloudBackend(LLMBackend):
+    """Cloud LLM backend using Anthropic or OpenAI APIs.
+
+    Usage:
+        backend = CloudBackend(model="claude-sonnet-4-20250514", api_key="sk-...")
+        for chunk in backend.generate(system_prompt, question):
+            print(chunk, end="")
+    """
+
+    def __init__(
+        self,
+        model: str = "claude-sonnet-4-20250514",
+        api_key: str | None = None,
+        max_output_tokens: int = 4096,
+    ):
+        """Initialize the cloud backend.
+
+        Args:
+            model: Model identifier (e.g., 'claude-sonnet-4-20250514', 'gpt-4o').
+            api_key: API key. If None, reads from environment variables.
+            max_output_tokens: Maximum tokens in the response.
+        """
+        self._model = _strip_provider_prefix(model)
+        self._provider = _detect_provider(model)
+        self._max_output_tokens = max_output_tokens
+
+        # Resolve API key
+        if api_key:
+            self._api_key = api_key
+        elif self._provider == "anthropic":
+            self._api_key = os.environ.get("ANTHROPIC_API_KEY")
+        elif self._provider == "openai":
+            self._api_key = os.environ.get("OPENAI_API_KEY")
+        else:
+            self._api_key = None
+
+    @property
+    def name(self) -> str:
+        provider_name = "Anthropic Claude" if self._provider == "anthropic" else "OpenAI"
+        return f"{provider_name} ({self._model})"
+
+    def validate(self) -> tuple[bool, str]:
+        """Check that the API key is set and the SDK is installed."""
+        if not self._api_key:
+            env_var = "ANTHROPIC_API_KEY" if self._provider == "anthropic" else "OPENAI_API_KEY"
+            return (
+                False,
+                f"No API key found. Set the {env_var} environment variable, "
+                f"or pass it in .repobrief.yml under 'api_key'.\n"
+                f"Example: export {env_var}=sk-your-key-here",
+            )
+
+        # Check if the SDK is installed
+        try:
+            if self._provider == "anthropic":
+                import anthropic  # noqa: F401
+            else:
+                import openai  # noqa: F401
+        except ImportError:
+            sdk = "anthropic" if self._provider == "anthropic" else "openai"
+            return (
+                False,
+                f"The '{sdk}' package is not installed. "
+                f"Install it with: pip install repobrief[cloud]",
+            )
+
+        return (True, f"Ready -- using {self.name}")
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_message: str,
+        history: list[ChatMessage] | None = None,
+    ) -> Iterator[str]:
+        """Send a prompt to the cloud API and stream back response tokens.
+
+        Args:
+            system_prompt: System instructions (includes the repo digest).
+            user_message: The user's question.
+            history: Previous conversation messages.
+
+        Yields:
+            String chunks of the response.
+        """
+        if self._provider == "anthropic":
+            yield from self._generate_anthropic(system_prompt, user_message, history)
+        else:
+            yield from self._generate_openai(system_prompt, user_message, history)
+
+    def _generate_anthropic(
+        self,
+        system_prompt: str,
+        user_message: str,
+        history: list[ChatMessage] | None = None,
+    ) -> Iterator[str]:
+        """Generate using the Anthropic API."""
+        import anthropic
+
+        client = anthropic.Anthropic(api_key=self._api_key)
+
+        # Build messages list
+        messages = []
+        if history:
+            for msg in history:
+                if msg.role in ("user", "assistant"):
+                    messages.append({"role": msg.role, "content": msg.content})
+        messages.append({"role": "user", "content": user_message})
+
+        try:
+            with client.messages.stream(
+                model=self._model,
+                max_tokens=self._max_output_tokens,
+                system=system_prompt,
+                messages=messages,
+            ) as stream:
+                yield from stream.text_stream
+        except anthropic.AuthenticationError as err:
+            raise PermissionError(
+                "Invalid Anthropic API key. Check your ANTHROPIC_API_KEY."
+            ) from err
+        except anthropic.RateLimitError as err:
+            raise RuntimeError(
+                "Anthropic API rate limit exceeded. Wait a moment and try again."
+            ) from err
+        except anthropic.APIConnectionError as err:
+            raise ConnectionError(
+                "Could not connect to the Anthropic API. Check your internet connection."
+            ) from err
+
+    def _generate_openai(
+        self,
+        system_prompt: str,
+        user_message: str,
+        history: list[ChatMessage] | None = None,
+    ) -> Iterator[str]:
+        """Generate using the OpenAI API."""
+        import openai
+
+        client = openai.OpenAI(api_key=self._api_key)
+
+        # Build messages list
+        messages = [{"role": "system", "content": system_prompt}]
+        if history:
+            for msg in history:
+                if msg.role in ("user", "assistant"):
+                    messages.append({"role": msg.role, "content": msg.content})
+        messages.append({"role": "user", "content": user_message})
+
+        try:
+            stream = client.chat.completions.create(
+                model=self._model,
+                messages=messages,
+                max_tokens=self._max_output_tokens,
+                stream=True,
+            )
+            for chunk in stream:
+                if chunk.choices and chunk.choices[0].delta.content:
+                    yield chunk.choices[0].delta.content
+        except openai.AuthenticationError as err:
+            raise PermissionError(
+                "Invalid OpenAI API key. Check your OPENAI_API_KEY."
+            ) from err
+        except openai.RateLimitError as err:
+            raise RuntimeError(
+                "OpenAI API rate limit exceeded. Wait a moment and try again."
+            ) from err
+        except openai.APIConnectionError as err:
+            raise ConnectionError(
+                "Could not connect to the OpenAI API. Check your internet connection."
+            ) from err

repobrief/backends/ollama.py

@@ -0,0 +1,209 @@
+"""Ollama local backend -- fully offline LLM chat via Ollama's REST API.
+
+Communicates with a locally running Ollama server (default: http://localhost:11434).
+No data leaves the user's machine. Requires Ollama to be installed and running
+with at least one model pulled.
+"""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Iterator
+
+import requests
+
+from repobrief.backends.base import ChatMessage, LLMBackend
+
+# Default Ollama server URL
+DEFAULT_OLLAMA_HOST = "http://localhost:11434"
+
+# Timeout for health checks and model listing (seconds)
+CHECK_TIMEOUT = 5
+
+# Timeout for generation requests -- set high because local models can be slow
+GENERATE_TIMEOUT = 300  # 5 minutes
+
+
+class OllamaBackend(LLMBackend):
+    """Ollama local backend.
+
+    Connects to a locally running Ollama server and sends chat requests.
+    All processing happens on the user's machine -- no data is sent externally.
+
+    Usage:
+        backend = OllamaBackend(model="llama3.1:8b")
+        is_valid, msg = backend.validate()
+        if is_valid:
+            for chunk in backend.generate(system_prompt, question):
+                print(chunk, end="")
+    """
+
+    def __init__(
+        self,
+        model: str = "llama3.2:3b",
+        host: str = DEFAULT_OLLAMA_HOST,
+    ):
+        """Initialize the Ollama backend.
+
+        Args:
+            model: Name of the Ollama model to use (e.g., 'llama3.1:8b').
+            host: Ollama server URL (default: http://localhost:11434).
+        """
+        self._model = model
+        self._host = host.rstrip("/")
+
+    @property
+    def name(self) -> str:
+        return f"Ollama ({self._model})"
+
+    # -- Server Communication --------------------------------------------------
+
+    def _is_server_running(self) -> bool:
+        """Check if the Ollama server is responding."""
+        try:
+            resp = requests.get(f"{self._host}/", timeout=CHECK_TIMEOUT)
+            return resp.status_code == 200
+        except (requests.ConnectionError, requests.Timeout):
+            return False
+
+    def _list_models(self) -> list[str]:
+        """Get list of locally available models.
+
+        Returns:
+            List of model name strings (e.g., ['llama3.1:8b', 'phi3:mini']).
+        """
+        try:
+            resp = requests.get(f"{self._host}/api/tags", timeout=CHECK_TIMEOUT)
+            if resp.status_code == 200:
+                data = resp.json()
+                models = data.get("models", [])
+                return [m["name"] for m in models]
+        except (requests.ConnectionError, requests.Timeout, ValueError, KeyError):
+            pass
+        return []
+
+    def _is_model_available(self) -> bool:
+        """Check if the configured model is available locally."""
+        available = self._list_models()
+        # Check exact match and partial match (with/without tag)
+        model_base = self._model.split(":")[0]
+        return (
+            self._model in available
+            or any(m.startswith(model_base) for m in available)
+        )
+
+    # -- LLMBackend Interface --------------------------------------------------
+
+    def validate(self) -> tuple[bool, str]:
+        """Check if Ollama is running and the model is available.
+
+        Returns:
+            (True, "Ready") if everything is configured.
+            (False, "detailed error message") if there's a problem.
+        """
+        # Check 1: Is Ollama running?
+        if not self._is_server_running():
+            return (
+                False,
+                f"Ollama server is not running at {self._host}.\n"
+                f"\n"
+                f"To fix this:\n"
+                f"  1. Install Ollama: https://ollama.com/download\n"
+                f"  2. Start the server: ollama serve\n"
+                f"  3. Pull a model: ollama pull {self._model}\n"
+                f"  4. Try again",
+            )
+
+        # Check 2: Is the model available?
+        if not self._is_model_available():
+            available = self._list_models()
+            available_str = ", ".join(available[:5]) if available else "(none)"
+            return (
+                False,
+                f"Model '{self._model}' is not available locally.\n"
+                f"\n"
+                f"Available models: {available_str}\n"
+                f"\n"
+                f"To fix this:\n"
+                f"  Pull the model: ollama pull {self._model}\n"
+                f"\n"
+                f"Recommended models for limited RAM:\n"
+                f"  - llama3.2:3b  (~2GB RAM) -- fast, good quality\n"
+                f"  - phi3:mini    (~2.3GB RAM) -- fast, good for code\n"
+                f"  - llama3.1:8b  (~4.5GB RAM) -- better quality, needs more RAM",
+            )
+
+        return (True, f"Ready -- using {self.name} (local, fully offline)")
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_message: str,
+        history: list[ChatMessage] | None = None,
+    ) -> Iterator[str]:
+        """Send a prompt to the local Ollama server and stream back response tokens.
+
+        Args:
+            system_prompt: System instructions (includes the repo digest).
+            user_message: The user's question.
+            history: Previous conversation messages.
+
+        Yields:
+            String chunks of the response as they arrive.
+        """
+        # Build messages array
+        messages: list[dict[str, str]] = [
+            {"role": "system", "content": system_prompt},
+        ]
+        if history:
+            for msg in history:
+                if msg.role in ("user", "assistant"):
+                    messages.append({"role": msg.role, "content": msg.content})
+        messages.append({"role": "user", "content": user_message})
+
+        # Send request with streaming
+        payload = {
+            "model": self._model,
+            "messages": messages,
+            "stream": True,
+        }
+
+        try:
+            resp = requests.post(
+                f"{self._host}/api/chat",
+                json=payload,
+                stream=True,
+                timeout=GENERATE_TIMEOUT,
+            )
+
+            if resp.status_code != 200:
+                error_text = resp.text[:500]
+                raise RuntimeError(
+                    f"Ollama returned HTTP {resp.status_code}: {error_text}"
+                )
+
+            # Parse streaming response (newline-delimited JSON)
+            for line in resp.iter_lines(decode_unicode=True):
+                if not line:
+                    continue
+                try:
+                    data = json.loads(line)
+                    content = data.get("message", {}).get("content", "")
+                    if content:
+                        yield content
+                    if data.get("done", False):
+                        break
+                except json.JSONDecodeError:
+                    continue  # Skip malformed lines
+
+        except requests.ConnectionError as err:
+            raise ConnectionError(
+                f"Lost connection to Ollama server at {self._host}. "
+                f"Make sure Ollama is still running."
+            ) from err
+        except requests.Timeout as err:
+            raise RuntimeError(
+                f"Ollama request timed out after {GENERATE_TIMEOUT} seconds. "
+                f"The model may be too large for your system, or the server "
+                f"is overloaded."
+            ) from err

repobrief/backends/prompts.py

@@ -0,0 +1,45 @@
+"""System prompt templates for chat mode.
+
+The system prompt includes the packed repo digest and instructions
+for how the LLM should behave when answering questions about the codebase.
+"""
+
+SYSTEM_PROMPT_TEMPLATE = """\
+You are RepoBrief, an expert code assistant. You have been given the \
+contents of a software repository and your job is to answer questions \
+about it accurately and helpfully.
+
+## Instructions
+
+1. **Answer based on the code provided.** Only reference files and code \
+that appear in the digest below. If the answer isn't in the provided \
+code, say so clearly -- do not guess or make up code that isn't there.
+
+2. **Be specific.** When referencing code, mention the exact file path \
+and relevant line content. Use code blocks for code snippets.
+
+3. **Be concise but thorough.** Give a direct answer first, then explain \
+the reasoning if needed.
+
+4. **Suggest improvements when relevant.** If you notice bugs, \
+anti-patterns, or potential improvements, mention them briefly.
+
+5. **Respect scope.** You can see only the files included in the digest. \
+There may be other files excluded due to token budget limits.
+
+## Repository Digest
+
+{digest}
+"""
+
+
+def build_system_prompt(digest: str) -> str:
+    """Build the complete system prompt with the repo digest embedded.
+
+    Args:
+        digest: The packed repository digest (from the packer module).
+
+    Returns:
+        Complete system prompt string.
+    """
+    return SYSTEM_PROMPT_TEMPLATE.format(digest=digest)