titan-cli 0.1.0__py3-none-any.whl

titan_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Titan CLI - Modular development tools orchestrator."""
+
+__version__ = "0.1.0"

titan_cli/__main__.py

@@ -0,0 +1,4 @@
+from titan_cli.cli import app
+
+if __name__ == "__main__":
+    app()

titan_cli/ai/agents/__init__.py

@@ -0,0 +1,15 @@
+# titan_cli/ai/agents/__init__.py
+"""AI Agents base classes.
+
+This module provides base classes for building AI agents.
+Specific agents live in their respective plugins.
+"""
+
+from .base import BaseAIAgent, AgentRequest, AgentResponse, AIGenerator
+
+__all__ = [
+    "BaseAIAgent",
+    "AgentRequest",
+    "AgentResponse",
+    "AIGenerator",
+]

titan_cli/ai/agents/base.py

@@ -0,0 +1,152 @@
+# titan_cli/ai/agents/base.py
+"""Base classes for AI agents."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Optional, Protocol, List
+
+from titan_cli.ai.models import AIMessage, AIResponse
+
+
+@dataclass
+class AgentRequest:
+    """Generic request for AI generation."""
+    context: str
+    max_tokens: int = 2000
+    temperature: float = 0.7
+    system_prompt: Optional[str] = None
+
+
+@dataclass
+class AgentResponse:
+    """Generic response from AI generation."""
+    content: str
+    tokens_used: int
+    provider: str
+    cached: bool = False
+
+
+class AIGenerator(Protocol):
+    """
+    Protocol defining the interface for AI generation.
+
+    This allows BaseAIAgent to depend on an abstraction rather than
+    concrete implementations like AIClient or AIProvider.
+
+    Any class implementing these methods can be used with agents.
+    """
+
+    def generate(
+        self,
+        messages: List[AIMessage],
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None
+    ) -> AIResponse:
+        """
+        Generate AI response from messages.
+
+        Args:
+            messages: List of AIMessage objects
+            max_tokens: Maximum tokens to generate
+            temperature: Sampling temperature
+
+        Returns:
+            AIResponse object with content and metadata
+        """
+        ...
+
+    def is_available(self) -> bool:
+        """
+        Check if AI generation is available.
+
+        Returns:
+            True if AI can be used
+        """
+        ...
+
+
+class BaseAIAgent(ABC):
+    """
+    Abstract base class for all AI agents.
+
+    Agents wrap AI generation with specialized domain logic.
+    They depend on AIGenerator protocol for loose coupling.
+    """
+
+    def __init__(self, generator: AIGenerator):
+        """
+        Initialize agent with AI generator.
+
+        Args:
+            generator: Any object implementing AIGenerator protocol
+                      (e.g., AIClient, AIProvider, or mock for testing)
+        """
+        self.generator = generator
+
+    @abstractmethod
+    def get_system_prompt(self) -> str:
+        """
+        Get the system prompt for this agent's expertise.
+
+        Each agent defines its specialized role.
+        """
+        pass
+
+    def generate(self, request: AgentRequest) -> AgentResponse:
+        """
+        Generate AI response using the underlying generator.
+
+        Args:
+            request: AgentRequest with context and parameters
+
+        Returns:
+            AgentResponse with generated content
+        """
+        # Build messages with system prompt
+        messages = []
+
+        # Use agent's system prompt if not overridden
+        system_prompt = request.system_prompt or self.get_system_prompt()
+        if system_prompt:
+            messages.append(AIMessage(role="system", content=system_prompt))
+
+        messages.append(AIMessage(role="user", content=request.context))
+
+        # Call underlying generator (AIClient, AIProvider, etc.)
+        response = self.generator.generate(
+            messages=messages,
+            max_tokens=request.max_tokens,
+            temperature=request.temperature
+        )
+
+        # Convert to AgentResponse
+        # Calculate tokens used - handle both patterns
+        if response.usage:
+            # Try total_tokens first (some providers)
+            tokens_used = response.usage.get("total_tokens", 0)
+
+            # If not available, try input_tokens + output_tokens (Anthropic, etc.)
+            if tokens_used == 0:
+                input_tokens = response.usage.get("input_tokens", 0)
+                output_tokens = response.usage.get("output_tokens", 0)
+                tokens_used = input_tokens + output_tokens
+        else:
+            tokens_used = 0
+
+        # Get provider name safely
+        try:
+            provider_obj = getattr(self.generator, '_provider', self.generator)
+            provider_name = provider_obj.__class__.__name__ if provider_obj else "Unknown"
+        except AttributeError:
+            provider_name = "Unknown"
+
+        return AgentResponse(
+            content=response.content,
+            tokens_used=tokens_used,
+            provider=provider_name,
+            cached=False
+        )
+
+    def is_available(self) -> bool:
+        """Check if AI is available."""
+        return self.generator and self.generator.is_available()

titan_cli/ai/client.py

@@ -0,0 +1,170 @@
+"""
+AI Client - Main facade for AI functionality
+"""
+
+from typing import Optional, List
+
+from titan_cli.core.models import AIConfig
+from titan_cli.core.secrets import SecretManager
+from .exceptions import AIConfigurationError
+from .models import AIMessage, AIRequest, AIResponse
+from .providers import AIProvider, AnthropicProvider, GeminiProvider
+
+# A mapping from provider names to classes
+PROVIDER_CLASSES = {
+    "anthropic": AnthropicProvider,
+    "gemini": GeminiProvider,
+}
+
+class AIClient:
+    """
+    Main client for AI functionality.
+
+    This facade simplifies AI usage by:
+    - Reading configuration from AIConfig.
+    - Retrieving secrets from SecretManager.
+    - Instantiating the correct AI provider.
+    - Providing a simple `generate()` and `chat()` interface.
+    """
+
+    def __init__(self, ai_config: AIConfig, secrets: SecretManager, provider_id: Optional[str] = None):
+        """
+        Initialize AI client.
+
+        Args:
+            ai_config: The AI configuration.
+            secrets: The SecretManager for handling API keys.
+            provider_id: The specific provider ID to use. If None, uses the default.
+        """
+        self.ai_config = ai_config
+        self.secrets = secrets
+
+        # Determine provider_id with fallback
+        requested_id = provider_id or ai_config.default
+
+        # Validate that the provider exists, fallback to first available if default is invalid
+        if requested_id and requested_id in ai_config.providers:
+            self.provider_id = requested_id
+        elif ai_config.providers:
+            # Fallback to first available provider
+            self.provider_id = list(ai_config.providers.keys())[0]
+        else:
+            raise AIConfigurationError("No AI providers configured.")
+
+        self._provider: Optional[AIProvider] = None
+
+    @property
+    def provider(self) -> AIProvider:
+        """
+        Get configured provider (lazy loading).
+
+        Returns:
+            Provider instance.
+
+        Raises:
+            AIConfigurationError: If AI is not enabled or configured incorrectly.
+        """
+        if self._provider:
+            return self._provider
+
+        provider_config = self.ai_config.providers.get(self.provider_id)
+        if not provider_config:
+            raise AIConfigurationError(f"AI provider '{self.provider_id}' not found in configuration.")
+
+        provider_name = provider_config.provider
+        provider_class = PROVIDER_CLASSES.get(provider_name)
+
+        if not provider_class:
+            raise AIConfigurationError(f"Unknown AI provider type: {provider_name}")
+
+        # Get API key
+        api_key_name = f"{self.provider_id}_api_key"
+        api_key = self.secrets.get(api_key_name)
+
+        if not api_key:
+            raise AIConfigurationError(f"API key for provider '{self.provider_id}' ({provider_name}) not found.")
+
+        kwargs = {"api_key": api_key, "model": provider_config.model}
+        if provider_config.base_url:
+            kwargs["base_url"] = provider_config.base_url
+
+        self._provider = provider_class(**kwargs)
+        return self._provider
+
+    def generate(
+        self,
+        messages: List[AIMessage],
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+    ) -> AIResponse:
+        """
+        Generate response using configured AI provider.
+
+        Args:
+            messages: List of conversation messages.
+            max_tokens: Optional override for the maximum number of tokens.
+            temperature: Optional override for the temperature.
+
+        Returns:
+            AI response with generated content.
+        """
+        provider_cfg = self.ai_config.providers.get(self.provider_id)
+        if not provider_cfg:
+            raise AIConfigurationError(f"AI provider '{self.provider_id}' not found for generation.")
+
+        request = AIRequest(
+            messages=messages,
+            max_tokens=max_tokens if max_tokens is not None else provider_cfg.max_tokens,
+            temperature=temperature if temperature is not None else provider_cfg.temperature,
+        )
+        return self.provider.generate(request)
+
+    def chat(
+        self,
+        prompt: str,
+        system_prompt: Optional[str] = None,
+        max_tokens: Optional[int] = None,
+        temperature: Optional[float] = None,
+    ) -> str:
+        """
+        Simple chat interface for single-turn conversations.
+
+        Args:
+            prompt: User prompt/question.
+            system_prompt: Optional system prompt to set context.
+            max_tokens: Optional override for the maximum number of tokens.
+            temperature: Optional override for the temperature.
+
+        Returns:
+            AI response text.
+        """
+        messages = []
+        if system_prompt:
+            messages.append(AIMessage(role="system", content=system_prompt))
+        messages.append(AIMessage(role="user", content=prompt))
+
+        response = self.generate(
+            messages, max_tokens=max_tokens, temperature=temperature
+        )
+        return response.content
+
+    def is_available(self) -> bool:
+        """
+        Check if AI is available and configured correctly.
+
+        Returns:
+            True if AI can be used.
+        """
+        if not self.ai_config or not self.ai_config.providers:
+            return False
+        
+        provider_cfg = self.ai_config.providers.get(self.provider_id)
+        if not provider_cfg:
+            return False
+
+        try:
+            # This will attempt to instantiate the provider, which includes key checks.
+            # Make sure to call self.provider to trigger the instantiation and checks
+            return self.provider is not None
+        except AIConfigurationError:
+            return False

titan_cli/ai/constants.py

@@ -0,0 +1,56 @@
+"""
+AI Provider Constants
+
+Minimal constants for AI providers. Models are not hardcoded to allow
+for easy updates and custom/enterprise model support.
+"""
+
+from typing import Dict
+
+
+# Default models (can be overridden by user)
+PROVIDER_DEFAULTS: Dict[str, str] = {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "gemini": "gemini-1.5-pro",
+}
+
+
+# Provider metadata
+PROVIDER_INFO: Dict[str, Dict[str, str]] = {
+    "anthropic": {
+        "name": "Claude (Anthropic)",
+        "api_key_url": "https://console.anthropic.com/",
+        "api_key_prefix": "sk-ant-",
+    },
+    "gemini": {
+        "name": "Gemini (Google)",
+        "api_key_url": "https://makersuite.google.com/app/apikey",
+        "api_key_prefix": "AIza",
+    },
+}
+
+
+def get_default_model(provider: str) -> str:
+    """
+    Get default model for a provider
+
+    Args:
+        provider: Provider key (e.g., "anthropic")
+
+    Returns:
+        Default model string
+    """
+    return PROVIDER_DEFAULTS.get(provider, "")
+
+
+def get_provider_name(provider: str) -> str:
+    """
+    Get human-readable provider name
+
+    Args:
+        provider: Provider key
+
+    Returns:
+        Provider display name
+    """
+    return PROVIDER_INFO.get(provider, {}).get("name", provider.title())

titan_cli/ai/exceptions.py

@@ -0,0 +1,48 @@
+"""
+Exceptions for AI system
+"""
+
+
+class AIError(Exception):
+    """Base exception for AI errors"""
+    pass
+
+
+class AIConfigurationError(AIError):
+    """AI configuration is invalid or missing"""
+    pass
+
+
+class AIProviderError(AIError):
+    """Base exception for AI provider errors"""
+    pass
+
+
+class AIProviderAuthenticationError(AIProviderError):
+    """Authentication failed (invalid API key)"""
+    pass
+
+
+class AIProviderRateLimitError(AIProviderError):
+    """Rate limit exceeded"""
+    pass
+
+
+class AIProviderAPIError(AIProviderError):
+    """API error from provider"""
+    pass
+
+
+class AIAnalysisError(AIError):
+    """Base exception for AI analysis errors"""
+    pass
+
+
+class AIResponseParseError(AIAnalysisError):
+    """Failed to parse AI response (e.g., invalid JSON)"""
+    pass
+
+
+class AINotAvailableError(AIError):
+    """AI is not available or not configured"""
+    pass

titan_cli/ai/models.py

@@ -0,0 +1,34 @@
+"""
+Data models for AI system
+"""
+
+from dataclasses import dataclass, field
+from typing import List, Dict
+
+
+@dataclass
+class AIMessage:
+    """Message in an AI conversation"""
+    role: str  # "system", "user", "assistant"
+    content: str
+
+    def to_dict(self) -> Dict[str, str]:
+        """Convert to dictionary for API calls"""
+        return {"role": self.role, "content": self.content}
+
+
+@dataclass
+class AIRequest:
+    """Request to an AI provider"""
+    messages: List[AIMessage]
+    max_tokens: int = 4096
+    temperature: float = 0.7
+
+
+@dataclass
+class AIResponse:
+    """Response from an AI provider"""
+    content: str
+    model: str
+    usage: Dict[str, int] = field(default_factory=dict)
+    finish_reason: str = "unknown"

titan_cli/ai/oauth_helper.py

@@ -0,0 +1,120 @@
+"""
+OAuth Helper for AI Providers
+
+Handles OAuth authentication for providers that support it (e.g., Gemini with gcloud).
+"""
+
+from typing import Optional, Tuple
+from dataclasses import dataclass
+
+from titan_cli.clients.gcloud_client import GCloudClient, GCloudClientError
+
+
+@dataclass
+class OAuthStatus:
+    """OAuth authentication status"""
+    available: bool
+    authenticated: bool
+    account: Optional[str] = None
+    error: Optional[str] = None
+
+
+class OAuthHelper:
+    """
+    Helper for OAuth authentication with AI providers
+
+    Currently supports:
+    - Google Cloud OAuth (gcloud) for Gemini
+
+    Examples:
+        >>> helper = OAuthHelper()
+        >>> status = helper.check_gcloud_auth()
+        >>> if status.authenticated:
+        ...     print(f"Authenticated as: {status.account}")
+    """
+
+    def __init__(self, gcloud_client: Optional[GCloudClient] = None):
+        self.gcloud = gcloud_client or GCloudClient()
+
+    def check_gcloud_auth(self) -> OAuthStatus:
+        """
+        Check if Google Cloud CLI is installed and authenticated
+
+        Returns:
+            OAuthStatus with authentication information
+        """
+        if not self.gcloud.is_installed():
+            return OAuthStatus(
+                available=False,
+                authenticated=False,
+                error="gcloud CLI not installed"
+            )
+
+        try:
+            account = self.gcloud.get_active_account()
+            if account:
+                return OAuthStatus(
+                    available=True,
+                    authenticated=True,
+                    account=account
+                )
+            else:
+                return OAuthStatus(
+                    available=True,
+                    authenticated=False,
+                    error="No active gcloud account found"
+                )
+        except GCloudClientError as e:
+            return OAuthStatus(
+                available=True, # It's installed, but auth failed
+                authenticated=False,
+                error=str(e)
+            )
+
+    @staticmethod
+    def get_install_instructions() -> str:
+        """
+        Get installation instructions for gcloud CLI
+
+        Returns:
+            Formatted installation instructions
+        """
+        return """Install Google Cloud CLI:
+
+1. Visit: https://cloud.google.com/sdk/docs/install
+2. Download and install for your platform
+3. Run: gcloud init
+4. Run: gcloud auth application-default login
+
+This will authenticate your Google account for use with Gemini."""
+
+    @staticmethod
+    def get_auth_instructions() -> str:
+        """
+        Get authentication instructions for gcloud
+
+        Returns:
+            Formatted authentication instructions
+        """
+        return """Authenticate with Google Cloud:
+
+Run: gcloud auth application-default login
+
+This will open your browser to sign in with your Google account."""
+
+    def validate_gcloud_auth(self) -> Tuple[bool, Optional[str]]:
+        """
+        Validate that gcloud auth is properly configured
+
+        Returns:
+            Tuple of (is_valid, error_message)
+        """
+        status = self.check_gcloud_auth()
+
+        if not status.available:
+            return False, status.error
+
+        if not status.authenticated:
+            return False, "Not authenticated. Run: gcloud auth application-default login"
+
+        return True, None

titan_cli/ai/providers/__init__.py

@@ -0,0 +1,9 @@
+from .base import AIProvider
+from .anthropic import AnthropicProvider
+from .gemini import GeminiProvider
+
+__all__ = [
+    "AIProvider",
+    "AnthropicProvider",
+    "GeminiProvider",
+]