brainify 0.1.0__py3-none-any.whl

brainify/__init__.py

@@ -0,0 +1,32 @@
+from brainify.client import Brain, Brainify
+from brainify.config import AIConfig, BrainifyConfig, SearchConfig
+from brainify.exceptions import (
+    AuthenticationError,
+    BrainifyError,
+    ConfigurationError,
+    ProviderError,
+    RateLimitError,
+    SearchError,
+)
+from brainify.providers import SUPPORTED_PROVIDERS
+from brainify.utils.detector import SmartSearchDetector
+
+__version__ = "0.1.0"
+__author__ = "Brainify"
+__license__ = "MIT"
+
+__all__ = [
+    "Brain",
+    "Brainify",
+    "BrainifyConfig",
+    "AIConfig",
+    "SearchConfig",
+    "SmartSearchDetector",
+    "BrainifyError",
+    "ProviderError",
+    "SearchError",
+    "ConfigurationError",
+    "RateLimitError",
+    "AuthenticationError",
+    "SUPPORTED_PROVIDERS",
+]

brainify/client.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+
+from typing import List, Optional
+
+from brainify.config import BrainifyConfig
+from brainify.providers.base import BaseProvider, Message
+from brainify.providers.factory import ProviderFactory
+from brainify.utils.context import ContextBuilder
+from brainify.utils.detector import SmartSearchDetector
+from brainify.utils.logger import get_logger
+from brainify.utils.prompts import PromptBuilder
+
+logger = get_logger(__name__)
+
+_DECISION_CACHE_MAX = 256
+
+
+class Brain:
+
+    def __init__(self, config: BrainifyConfig):
+        self._config = config
+        self._provider: BaseProvider = ProviderFactory.create(config.ai)
+        self._context_builder: ContextBuilder = ContextBuilder(config.search)
+        self._history: List[Message] = []
+        self._decision_cache: dict[str, bool] = {}
+        logger.info(
+            "Brain initialised — provider=%s model=%s enabled=%s auto_search=%s",
+            config.ai.provider,
+            config.ai.model,
+            config.search.enabled,
+            config.search.auto_search,
+        )
+
+    def chat(
+        self,
+        query: str,
+        *,
+        web_search: Optional[bool] = None,
+        clear_history: bool = False,
+    ) -> str:
+        if clear_history:
+            self.clear_history()
+
+        use_search = self._resolve_search_flag(web_search, query)
+        system_prompt, _ = self._prepare_system(query, use_search)
+        messages = self._build_messages(query, system_prompt)
+        response = self._provider.complete(messages)
+
+        self._history.append(Message("user", query))
+        self._history.append(Message("assistant", response))
+        return response
+
+    def ask(self, query: str, *, web_search: Optional[bool] = None) -> str:
+        return self.chat(query, web_search=web_search, clear_history=True)
+
+    async def achat(
+        self,
+        query: str,
+        *,
+        web_search: Optional[bool] = None,
+        clear_history: bool = False,
+    ) -> str:
+        if clear_history:
+            self.clear_history()
+
+        use_search = await self._aresolve_search_flag(web_search, query)
+        system_prompt, _ = await self._aprepare_system(query, use_search)
+        messages = self._build_messages(query, system_prompt)
+        response = await self._provider.acomplete(messages)
+
+        self._history.append(Message("user", query))
+        self._history.append(Message("assistant", response))
+        return response
+
+    async def aask(self, query: str, *, web_search: Optional[bool] = None) -> str:
+        return await self.achat(query, web_search=web_search, clear_history=True)
+
+    def search_needed(self, query: str) -> bool:
+        return SmartSearchDetector.needs_search(query)
+
+    def search_explain(self, query: str) -> dict:
+        return SmartSearchDetector.explain(query)
+
+    def clear_history(self) -> None:
+        self._history.clear()
+        logger.debug("Conversation history cleared.")
+
+    def clear_decision_cache(self) -> None:
+        self._decision_cache.clear()
+        logger.debug("LLM decision cache cleared.")
+
+    @property
+    def history(self) -> List[Message]:
+        return list(self._history)
+
+    def add_to_history(self, role: str, content: str) -> None:
+        self._history.append(Message(role, content))
+
+    def clear_search_cache(self) -> None:
+        self._context_builder.clear_cache()
+        logger.debug("Search cache cleared.")
+
+    @property
+    def search_cache_size(self) -> int:
+        return self._context_builder.cache_size
+
+    @property
+    def config(self) -> BrainifyConfig:
+        return self._config
+
+    @property
+    def provider_name(self) -> str:
+        return self._config.ai.provider
+
+    @property
+    def model(self) -> str:
+        return self._config.ai.model
+
+    @property
+    def web_search_enabled(self) -> bool:
+        return self._config.search.enabled
+
+    @property
+    def auto_search_enabled(self) -> bool:
+        return self._config.search.auto_search
+
+    def _resolve_search_flag(self, override: Optional[bool], query: str) -> bool:
+        if override is not None:
+            return override
+        if self._config.search.enabled:
+            return True
+        if self._config.search.auto_search:
+            return self._llm_search_decision(query)
+        return False
+
+    async def _aresolve_search_flag(self, override: Optional[bool], query: str) -> bool:
+        if override is not None:
+            return override
+        if self._config.search.enabled:
+            return True
+        if self._config.search.auto_search:
+            return await self._allm_search_decision(query)
+        return False
+
+    def _llm_search_decision(self, query: str) -> bool:
+        cache_key = query.strip().lower()
+        if cache_key in self._decision_cache:
+            cached = self._decision_cache[cache_key]
+            logger.debug("Decision cache hit: %s for %r", "SEARCH" if cached else "SKIP", query[:60])
+            return cached
+
+        try:
+            sys_prompt, usr_prompt = PromptBuilder.classifier_prompt(query)
+            classifier_messages = [
+                Message("system", sys_prompt),
+                Message("user", usr_prompt),
+            ]
+            raw = self._provider.complete(classifier_messages)
+            decision = self._parse_classifier_response(raw, query)
+        except Exception as exc:
+            logger.warning("LLM classifier error (%s) — keyword fallback for: %r", exc, query[:60])
+            decision = SmartSearchDetector.needs_search(query)
+
+        self._store_decision(cache_key, decision)
+        return decision
+
+    async def _allm_search_decision(self, query: str) -> bool:
+        cache_key = query.strip().lower()
+        if cache_key in self._decision_cache:
+            cached = self._decision_cache[cache_key]
+            logger.debug("Decision cache hit: %s for %r", "SEARCH" if cached else "SKIP", query[:60])
+            return cached
+
+        try:
+            sys_prompt, usr_prompt = PromptBuilder.classifier_prompt(query)
+            classifier_messages = [
+                Message("system", sys_prompt),
+                Message("user", usr_prompt),
+            ]
+            raw = await self._provider.acomplete(classifier_messages)
+            decision = self._parse_classifier_response(raw, query)
+        except Exception as exc:
+            logger.warning("LLM classifier error (%s) — keyword fallback for: %r", exc, query[:60])
+            decision = SmartSearchDetector.needs_search(query)
+
+        self._store_decision(cache_key, decision)
+        return decision
+
+    def _parse_classifier_response(self, raw: str, query: str) -> bool:
+        answer = raw.strip().upper()
+        if answer.startswith("YES"):
+            logger.info("LLM decision → SEARCH  | query: %r", query[:80])
+            return True
+        if answer.startswith("NO"):
+            logger.info("LLM decision → SKIP    | query: %r", query[:80])
+            return False
+        logger.warning(
+            "Ambiguous LLM classifier response %r — keyword fallback for: %r",
+            raw[:30],
+            query[:60],
+        )
+        return SmartSearchDetector.needs_search(query)
+
+    def _store_decision(self, key: str, decision: bool) -> None:
+        if len(self._decision_cache) >= _DECISION_CACHE_MAX:
+            oldest = next(iter(self._decision_cache))
+            del self._decision_cache[oldest]
+        self._decision_cache[key] = decision
+
+    def _prepare_system(self, query: str, use_search: bool):
+        search_context = ""
+        search_results = []
+
+        if use_search:
+            try:
+                search_context, search_results = self._context_builder.build(query)
+            except Exception as exc:
+                logger.warning("Web search failed, continuing without it: %s", exc)
+
+        has_context = bool(search_context)
+        system_prompt = PromptBuilder.build(
+            web_search_active=use_search and has_context,
+            user_system_prompt=self._config.ai.system_prompt,
+            search_context=search_context if has_context else None,
+        )
+        if use_search and not has_context:
+            system_prompt += PromptBuilder.no_search_fallback_note()
+
+        return system_prompt, search_results
+
+    async def _aprepare_system(self, query: str, use_search: bool):
+        search_context = ""
+        search_results = []
+
+        if use_search:
+            try:
+                search_context, search_results = await self._context_builder.abuild(query)
+            except Exception as exc:
+                logger.warning("Async web search failed: %s", exc)
+
+        has_context = bool(search_context)
+        system_prompt = PromptBuilder.build(
+            web_search_active=use_search and has_context,
+            user_system_prompt=self._config.ai.system_prompt,
+            search_context=search_context if has_context else None,
+        )
+        if use_search and not has_context:
+            system_prompt += PromptBuilder.no_search_fallback_note()
+
+        return system_prompt, search_results
+
+    def _build_messages(self, query: str, system_prompt: str) -> List[Message]:
+        messages: List[Message] = [Message("system", system_prompt)]
+        messages.extend(self._history)
+        messages.append(Message("user", query))
+        return messages
+
+    def __repr__(self) -> str:
+        return (
+            f"Brain(provider={self.provider_name!r}, "
+            f"model={self.model!r}, "
+            f"enabled={self.web_search_enabled}, "
+            f"auto_search={self.auto_search_enabled})"
+        )
+
+
+Brainify = Brain

brainify/config.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+from brainify.exceptions import ConfigurationError
+
+
+@dataclass
+class AIConfig:
+    provider: str
+    api_key: str = ""
+    model: str = ""
+    temperature: float = 0.7
+    max_tokens: int = 2048
+    top_p: float = 1.0
+    top_k: Optional[int] = None
+    frequency_penalty: float = 0.0
+    presence_penalty: float = 0.0
+    system_prompt: Optional[str] = None
+    base_url: Optional[str] = None
+    timeout: int = 60
+    extra_headers: Dict[str, str] = field(default_factory=dict)
+    extra_params: Dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        self.provider = self.provider.lower().strip()
+        valid_providers = {
+            "openai", "anthropic", "gemini", "groq",
+            "mistral", "cohere", "together", "ollama", "custom",
+        }
+        if self.provider not in valid_providers:
+            raise ConfigurationError(
+                f"Unknown provider '{self.provider}'. "
+                f"Supported: {', '.join(sorted(valid_providers))}"
+            )
+        if not self.api_key and self.provider not in {"ollama", "custom"}:
+            raise ConfigurationError(
+                f"api_key is required for provider '{self.provider}'."
+            )
+        if not (0.0 <= self.temperature <= 2.0):
+            raise ConfigurationError("temperature must be between 0.0 and 2.0.")
+        if self.max_tokens < 1:
+            raise ConfigurationError("max_tokens must be >= 1.")
+
+    @property
+    def is_openai_compatible(self) -> bool:
+        return self.provider in {"openai", "groq", "together", "custom", "ollama"}
+
+
+@dataclass
+class SearchConfig:
+    enabled: bool = True
+    auto_search: bool = False
+    max_results: int = 5
+    max_pages_to_read: int = 3
+    max_content_length: int = 6000
+    search_timeout: int = 15
+    cache_ttl: int = 3600
+    safe_search: bool = True
+    region: str = "wt-wt"
+    time_filter: Optional[str] = None
+    excluded_domains: List[str] = field(default_factory=list)
+    include_snippets: bool = True
+    scrape_concurrency: int = 3
+    user_agent: Optional[str] = None
+
+    def __post_init__(self):
+        if self.max_results < 1 or self.max_results > 20:
+            raise ConfigurationError("max_results must be between 1 and 20.")
+        if self.max_pages_to_read < 0:
+            raise ConfigurationError("max_pages_to_read must be >= 0.")
+        if self.time_filter and self.time_filter not in {"d", "w", "m", "y"}:
+            raise ConfigurationError(
+                "time_filter must be one of: 'd', 'w', 'm', 'y'."
+            )
+
+
+@dataclass
+class BrainifyConfig:
+    ai: AIConfig
+    search: SearchConfig = field(default_factory=SearchConfig)

brainify/exceptions.py

@@ -0,0 +1,70 @@
+"""Custom exceptions for Brainify."""
+
+
+class BrainifyError(Exception):
+    """Base exception for all Brainify errors."""
+
+    def __init__(self, message: str, details: dict = None):
+        super().__init__(message)
+        self.message = message
+        self.details = details or {}
+
+    def __repr__(self):
+        return f"{self.__class__.__name__}(message={self.message!r})"
+
+
+class ConfigurationError(BrainifyError):
+    """Raised when configuration is invalid or missing."""
+
+
+class ProviderError(BrainifyError):
+    """Raised when an AI provider returns an error."""
+
+    def __init__(self, message: str, provider: str = None, status_code: int = None, details: dict = None):
+        super().__init__(message, details)
+        self.provider = provider
+        self.status_code = status_code
+
+
+class AuthenticationError(ProviderError):
+    """Raised when API key authentication fails."""
+
+
+class RateLimitError(ProviderError):
+    """Raised when the API rate limit is exceeded."""
+
+    def __init__(self, message: str, provider: str = None, retry_after: float = None, details: dict = None):
+        super().__init__(message, provider=provider, details=details)
+        self.retry_after = retry_after
+
+
+class SearchError(BrainifyError):
+    """Raised when a web search fails."""
+
+
+class ScrapingError(BrainifyError):
+    """Raised when web page scraping fails."""
+
+
+class ModelNotSupportedError(ConfigurationError):
+    """Raised when the model is not supported by the provider."""
+
+    def __init__(self, model: str, provider: str):
+        super().__init__(
+            f"Model '{model}' is not supported by provider '{provider}'. "
+            f"Check the provider documentation for supported models."
+        )
+        self.model = model
+        self.provider = provider
+
+
+class ProviderNotInstalledError(ConfigurationError):
+    """Raised when the required provider package is not installed."""
+
+    def __init__(self, provider: str, package: str):
+        super().__init__(
+            f"Provider '{provider}' requires the '{package}' package. "
+            f"Install it with: pip install brainify[{provider}]"
+        )
+        self.provider = provider
+        self.package = package

brainify/providers/__init__.py

@@ -0,0 +1,17 @@
+"""AI provider implementations."""
+
+from brainify.providers.factory import ProviderFactory
+
+SUPPORTED_PROVIDERS = [
+    "openai",
+    "anthropic",
+    "gemini",
+    "groq",
+    "mistral",
+    "cohere",
+    "together",
+    "ollama",
+    "custom",
+]
+
+__all__ = ["ProviderFactory", "SUPPORTED_PROVIDERS"]

brainify/providers/anthropic.py

@@ -0,0 +1,120 @@
+"""Anthropic provider (Claude 3.5, Claude 3, …)."""
+
+from __future__ import annotations
+
+from typing import List
+
+from brainify.config import AIConfig
+from brainify.exceptions import (
+    AuthenticationError,
+    ProviderError,
+    RateLimitError,
+    ProviderNotInstalledError,
+)
+from brainify.providers.base import BaseProvider, Message
+from brainify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class AnthropicProvider(BaseProvider):
+    """
+    Adapter for the Anthropic Messages API.
+
+    Supports: claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022,
+              claude-3-opus-20240229, claude-3-haiku-20240307, etc.
+
+    Install: pip install anthropic
+    """
+
+    def __init__(self, config: AIConfig):
+        super().__init__(config)
+        self._client = self._build_client()
+
+    def _build_client(self):
+        try:
+            from anthropic import Anthropic
+        except ImportError as exc:
+            raise ProviderNotInstalledError("anthropic", "anthropic") from exc
+
+        kwargs = {"api_key": self.config.api_key, "timeout": self.config.timeout}
+        if self.config.base_url:
+            kwargs["base_url"] = self.config.base_url
+        if self.config.extra_headers:
+            kwargs["default_headers"] = self.config.extra_headers
+        return Anthropic(**kwargs)
+
+    def complete(self, messages: List[Message]) -> str:
+        system_text = ""
+        chat_messages = []
+        for m in messages:
+            if m.role == "system":
+                system_text = m.content
+            else:
+                chat_messages.append(m.to_dict())
+
+        try:
+            params = {
+                "model": self.config.model,
+                "messages": chat_messages,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+                "top_p": self.config.top_p,
+            }
+            if system_text:
+                params["system"] = system_text
+            if self.config.top_k is not None:
+                params["top_k"] = self.config.top_k
+            params.update(self.config.extra_params)
+
+            logger.debug("Anthropic request: model=%s", self.config.model)
+            response = self._client.messages.create(**params)
+            result = response.content[0].text if response.content else ""
+            return result
+
+        except Exception as exc:
+            self._handle_error(exc)
+
+    async def acomplete(self, messages: List[Message]) -> str:
+        try:
+            from anthropic import AsyncAnthropic
+        except ImportError as exc:
+            raise ProviderNotInstalledError("anthropic", "anthropic") from exc
+
+        system_text = ""
+        chat_messages = []
+        for m in messages:
+            if m.role == "system":
+                system_text = m.content
+            else:
+                chat_messages.append(m.to_dict())
+
+        kwargs = {"api_key": self.config.api_key, "timeout": self.config.timeout}
+        async with AsyncAnthropic(**kwargs) as client:
+            params = {
+                "model": self.config.model,
+                "messages": chat_messages,
+                "max_tokens": self.config.max_tokens,
+                "temperature": self.config.temperature,
+            }
+            if system_text:
+                params["system"] = system_text
+            params.update(self.config.extra_params)
+            response = await client.messages.create(**params)
+            return response.content[0].text if response.content else ""
+
+    def _handle_error(self, exc: Exception):
+        try:
+            from anthropic import AuthenticationError as AAuth
+            from anthropic import RateLimitError as ARate
+            from anthropic import APIError
+        except ImportError:
+            raise ProviderError(str(exc), provider="anthropic") from exc
+
+        if isinstance(exc, AAuth):
+            raise AuthenticationError("Invalid Anthropic API key.", provider="anthropic") from exc
+        if isinstance(exc, ARate):
+            raise RateLimitError("Anthropic rate limit exceeded.", provider="anthropic") from exc
+        if isinstance(exc, APIError):
+            raise ProviderError(f"Anthropic API error: {exc}", provider="anthropic") from exc
+        raise ProviderError(f"Anthropic unexpected error: {exc}", provider="anthropic") from exc

brainify/providers/base.py

@@ -0,0 +1,102 @@
+"""Abstract base class for all AI providers."""
+
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import List, Optional
+
+from brainify.config import AIConfig
+from brainify.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class Message:
+    """A single chat message."""
+
+    def __init__(self, role: str, content: str):
+        if role not in {"system", "user", "assistant"}:
+            raise ValueError(f"Invalid role: {role!r}. Must be system/user/assistant.")
+        self.role = role
+        self.content = content
+
+    def to_dict(self) -> dict:
+        return {"role": self.role, "content": self.content}
+
+    def __repr__(self) -> str:
+        preview = self.content[:60] + "…" if len(self.content) > 60 else self.content
+        return f"Message(role={self.role!r}, content={preview!r})"
+
+
+class BaseProvider(ABC):
+    """
+    Abstract base for all Brainify AI provider adapters.
+
+    Subclasses must implement :meth:`complete` (sync) and may override
+    :meth:`acomplete` (async) for native async support.
+    """
+
+    def __init__(self, config: AIConfig):
+        self.config = config
+        self.provider_name: str = config.provider
+
+
+    @abstractmethod
+    def complete(self, messages: List[Message]) -> str:
+        """
+        Send messages to the AI and return the response string.
+
+        Args:
+            messages: Ordered list of chat messages (system, user, assistant…).
+
+        Returns:
+            The AI's response text.
+
+        Raises:
+            ProviderError: On API errors.
+            AuthenticationError: On 401/403 responses.
+            RateLimitError: On 429 responses.
+        """
+
+
+    async def acomplete(self, messages: List[Message]) -> str:
+        """
+        Async version of :meth:`complete`.
+
+        Default implementation runs the sync version in a thread pool.
+        Override in subclasses for native async support.
+        """
+        return await asyncio.get_event_loop().run_in_executor(
+            None, self.complete, messages
+        )
+
+
+    def _build_messages(
+        self,
+        user_message: str,
+        system_prompt: Optional[str] = None,
+        history: Optional[List[Message]] = None,
+    ) -> List[Message]:
+        """Build a full message list from components."""
+        messages: List[Message] = []
+        if system_prompt:
+            messages.append(Message("system", system_prompt))
+        if history:
+            messages.extend(history)
+        messages.append(Message("user", user_message))
+        return messages
+
+    def _get_common_params(self) -> dict:
+        """Return common generation parameters from config."""
+        params = {
+            "temperature": self.config.temperature,
+            "max_tokens": self.config.max_tokens,
+        }
+        if self.config.top_p != 1.0:
+            params["top_p"] = self.config.top_p
+        params.update(self.config.extra_params)
+        return params
+
+    def __repr__(self) -> str:
+        return f"{self.__class__.__name__}(model={self.config.model!r})"