maestro-core 0.2.0__tar.gz

maestro_core-0.2.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+archive/
+.omx/
+.clawd-agents/
+# Claude Code local artifacts
+.claude/settings.local.json
+.claude/sessions/

maestro_core-0.2.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: maestro-core
+Version: 0.2.0
+Summary: Core engine for Maestro AI agent — providers, trust layer, tools, conversation engine
+Project-URL: Homepage, https://github.com/oke-pro/maestro
+Project-URL: Repository, https://github.com/oke-pro/maestro
+Author-email: Yann Chappuit <yann@oke.pro>
+License: MIT
+Keywords: ai,anonymization,llm,multi-provider,privacy,tool-calling,trust-layer
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=0.44.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: openai>=1.60.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# maestro-core
+
+Core engine for Maestro AI agent. Multi-provider, privacy-first.
+
+## Features
+
+- **4 LLM Providers**: Anthropic (Claude), OpenAI (GPT), Google (Gemini), Ollama (local)
+- **Trust Layer**: Automatic anonymization of sensitive data (NIR, SIRET, IBAN, emails, names, API keys)
+- **Provider Router**: Auto-route to local/cloud based on data sensitivity
+- **Conversation Engine**: Turn loop with tool calling
+- **Tool Framework**: Base classes + 6 built-in tools (bash, file_read, file_write, file_edit, grep, glob)
+
+## Installation
+
+```bash
+pip install maestro-core
+```
+
+## Usage
+
+```python
+from maestro_core.engine import ConversationEngine
+from maestro_core.provider_router import ProviderRouter, RoutingMode
+from maestro_core.tools import ToolRegistry
+from maestro_core.tools.bash import BashTool
+from maestro_core.config import MaestroConfig
+from maestro_core.trust.anonymizer import TrustMode
+
+# Setup
+config = MaestroConfig()
+router = ProviderRouter(config, RoutingMode.AUTO, TrustMode.STANDARD)
+
+tools = ToolRegistry()
+tools.register(BashTool())
+
+engine = ConversationEngine(router=router, tools=tools)
+
+# Chat
+result = await engine.run_turn("List Python files", model="claude-sonnet-4")
+print(result.response_text)
+```
+
+## Trust Layer
+
+```python
+from maestro_core.trust.anonymizer import Anonymizer, TrustMode
+
+anon = Anonymizer(TrustMode.STANDARD)
+safe = anon.anonymize_text("NIR 267041305561777 SIRET 41021468800013")
+# → "NIR [NIR_1] SIRET [SIRET_1]"
+
+restored = anon.deanonymize_text(safe)
+# → "NIR 267041305561777 SIRET 41021468800013"
+```

maestro_core-0.2.0/README.md

@@ -0,0 +1,54 @@
+# maestro-core
+
+Core engine for Maestro AI agent. Multi-provider, privacy-first.
+
+## Features
+
+- **4 LLM Providers**: Anthropic (Claude), OpenAI (GPT), Google (Gemini), Ollama (local)
+- **Trust Layer**: Automatic anonymization of sensitive data (NIR, SIRET, IBAN, emails, names, API keys)
+- **Provider Router**: Auto-route to local/cloud based on data sensitivity
+- **Conversation Engine**: Turn loop with tool calling
+- **Tool Framework**: Base classes + 6 built-in tools (bash, file_read, file_write, file_edit, grep, glob)
+
+## Installation
+
+```bash
+pip install maestro-core
+```
+
+## Usage
+
+```python
+from maestro_core.engine import ConversationEngine
+from maestro_core.provider_router import ProviderRouter, RoutingMode
+from maestro_core.tools import ToolRegistry
+from maestro_core.tools.bash import BashTool
+from maestro_core.config import MaestroConfig
+from maestro_core.trust.anonymizer import TrustMode
+
+# Setup
+config = MaestroConfig()
+router = ProviderRouter(config, RoutingMode.AUTO, TrustMode.STANDARD)
+
+tools = ToolRegistry()
+tools.register(BashTool())
+
+engine = ConversationEngine(router=router, tools=tools)
+
+# Chat
+result = await engine.run_turn("List Python files", model="claude-sonnet-4")
+print(result.response_text)
+```
+
+## Trust Layer
+
+```python
+from maestro_core.trust.anonymizer import Anonymizer, TrustMode
+
+anon = Anonymizer(TrustMode.STANDARD)
+safe = anon.anonymize_text("NIR 267041305561777 SIRET 41021468800013")
+# → "NIR [NIR_1] SIRET [SIRET_1]"
+
+restored = anon.deanonymize_text(safe)
+# → "NIR 267041305561777 SIRET 41021468800013"
+```

maestro_core-0.2.0/maestro_core/__init__.py

@@ -0,0 +1,12 @@
+"""Maestro Core — moteur multi-provider avec trust layer."""
+
+__version__ = "0.1.0"
+
+from .config import MaestroConfig
+from .provider_router import ProviderRouter, RoutingMode
+
+__all__ = [
+    "MaestroConfig",
+    "ProviderRouter",
+    "RoutingMode",
+]

maestro_core-0.2.0/maestro_core/api/__init__.py

@@ -0,0 +1,136 @@
+"""Package API — traduit de api/lib.rs.
+
+Fournit les clients multi-provider (Anthropic, xAI, OpenAI),
+le parsing SSE, le prompt cache et tous les types de l'API Messages.
+"""
+
+from .client import (
+    MessageStream,
+    ProviderClient,
+    read_xai_base_url,
+)
+from .error import (
+    ApiError,
+    ApiResponseError,
+    AuthError,
+    BackoffOverflowError,
+    ExpiredOAuthTokenError,
+    HttpError,
+    InvalidApiKeyEnvError,
+    InvalidSseFrameError,
+    IoError,
+    JsonError,
+    MissingCredentialsError,
+    RetriesExhaustedError,
+)
+from .prompt_cache import (
+    CacheBreakEvent,
+    PromptCache,
+    PromptCacheConfig,
+    PromptCachePaths,
+    PromptCacheRecord,
+    PromptCacheStats,
+)
+from .providers import (
+    ProviderKind,
+    detect_provider_kind,
+    max_tokens_for_model,
+    resolve_model_alias,
+)
+from .providers.anthropic import (
+    AnthropicClient,
+    AuthSource,
+    OAuthTokenSet,
+    oauth_token_is_expired,
+    read_base_url,
+    resolve_saved_oauth_token,
+    resolve_startup_auth_source,
+)
+from .providers.openai_compat import (
+    OpenAiCompatClient,
+    OpenAiCompatConfig,
+)
+from .sse import SseParser, parse_frame
+from .types import (
+    ContentBlockDelta,
+    ContentBlockDeltaEvent,
+    ContentBlockStartEvent,
+    ContentBlockStopEvent,
+    InputContentBlock,
+    InputMessage,
+    MessageDelta,
+    MessageDeltaEvent,
+    MessageRequest,
+    MessageResponse,
+    MessageStartEvent,
+    MessageStopEvent,
+    OutputContentBlock,
+    StreamEvent,
+    ToolChoice,
+    ToolDefinition,
+    ToolResultContentBlock,
+    Usage,
+)
+
+__all__ = [
+    # Client
+    "ProviderClient",
+    "MessageStream",
+    "read_xai_base_url",
+    # Error
+    "ApiError",
+    "ApiResponseError",
+    "AuthError",
+    "BackoffOverflowError",
+    "ExpiredOAuthTokenError",
+    "HttpError",
+    "InvalidApiKeyEnvError",
+    "InvalidSseFrameError",
+    "IoError",
+    "JsonError",
+    "MissingCredentialsError",
+    "RetriesExhaustedError",
+    # Prompt cache
+    "CacheBreakEvent",
+    "PromptCache",
+    "PromptCacheConfig",
+    "PromptCachePaths",
+    "PromptCacheRecord",
+    "PromptCacheStats",
+    # Providers
+    "AnthropicClient",
+    "AuthSource",
+    "OAuthTokenSet",
+    "OpenAiCompatClient",
+    "OpenAiCompatConfig",
+    "ProviderKind",
+    "detect_provider_kind",
+    "max_tokens_for_model",
+    "oauth_token_is_expired",
+    "read_base_url",
+    "resolve_model_alias",
+    "resolve_saved_oauth_token",
+    "resolve_startup_auth_source",
+    # SSE
+    "SseParser",
+    "parse_frame",
+    # Types
+    "ContentBlockDelta",
+    "ContentBlockDeltaEvent",
+    "ContentBlockStartEvent",
+    "ContentBlockStopEvent",
+    "InputContentBlock",
+    "InputMessage",
+    "MessageDelta",
+    "MessageDeltaEvent",
+    "MessageRequest",
+    "MessageResponse",
+    "MessageStartEvent",
+    "MessageStopEvent",
+    "OutputContentBlock",
+    "StreamEvent",
+    "ToolChoice",
+    "ToolDefinition",
+    "ToolResultContentBlock",
+    "Usage",
+]

maestro_core-0.2.0/maestro_core/api/client.py

@@ -0,0 +1,132 @@
+"""Client provider unifié — traduit de client.rs.
+
+Abstraction qui route vers Anthropic, xAI ou OpenAI
+selon le modèle demandé.
+"""
+
+from __future__ import annotations
+
+from typing import Optional, Union
+
+from .error import ApiError
+from .prompt_cache import PromptCache, PromptCacheRecord, PromptCacheStats
+from .providers import ProviderKind, detect_provider_kind, resolve_model_alias
+from .providers.anthropic import (
+    AnthropicClient,
+    AnthropicMessageStream,
+    AuthSource,
+    OAuthTokenSet,
+    oauth_token_is_expired,
+    read_base_url,
+    resolve_saved_oauth_token,
+    resolve_startup_auth_source,
+)
+from .providers.openai_compat import (
+    OpenAiCompatClient,
+    OpenAiCompatConfig,
+    OpenAiMessageStream,
+)
+from .types import MessageRequest, MessageResponse, StreamEvent
+
+
+# Union des streams
+MessageStream = Union[AnthropicMessageStream, OpenAiMessageStream]
+
+
+class ProviderClient:
+    """Client unifié multi-provider.
+
+    Route automatiquement vers le bon provider (Anthropic, xAI, OpenAI)
+    en fonction du modèle.
+    """
+
+    def __init__(
+        self,
+        kind: ProviderKind,
+        anthropic: Optional[AnthropicClient] = None,
+        openai_compat: Optional[OpenAiCompatClient] = None,
+    ) -> None:
+        self._kind = kind
+        self._anthropic = anthropic
+        self._openai_compat = openai_compat
+
+    @classmethod
+    def from_model(cls, model: str) -> ProviderClient:
+        """Crée un client depuis un nom de modèle."""
+        return cls.from_model_with_anthropic_auth(model, None)
+
+    @classmethod
+    def from_model_with_anthropic_auth(
+        cls, model: str, anthropic_auth: Optional[AuthSource] = None
+    ) -> ProviderClient:
+        """Crée un client avec une source d'auth spécifique pour Anthropic."""
+        resolved = resolve_model_alias(model)
+        kind = detect_provider_kind(resolved)
+
+        if kind == ProviderKind.ANTHROPIC:
+            if anthropic_auth is not None:
+                client = AnthropicClient.from_auth(anthropic_auth)
+            else:
+                client = AnthropicClient.from_env()
+            return cls(kind=kind, anthropic=client)
+        elif kind == ProviderKind.XAI:
+            client = OpenAiCompatClient.from_env(OpenAiCompatConfig.xai())
+            return cls(kind=kind, openai_compat=client)
+        elif kind == ProviderKind.OPENAI:
+            client = OpenAiCompatClient.from_env(OpenAiCompatConfig.openai())
+            return cls(kind=kind, openai_compat=client)
+        else:
+            raise ApiError(f"unsupported provider kind: {kind}")
+
+    @property
+    def provider_kind(self) -> ProviderKind:
+        """Type de provider utilisé."""
+        return self._kind
+
+    def with_prompt_cache(self, prompt_cache: PromptCache) -> ProviderClient:
+        """Attache un prompt cache (Anthropic seulement)."""
+        if self._anthropic is not None:
+            self._anthropic = self._anthropic.with_prompt_cache(prompt_cache)
+        return self
+
+    def prompt_cache_stats(self) -> Optional[PromptCacheStats]:
+        """Retourne les stats du prompt cache."""
+        if self._anthropic is not None:
+            return self._anthropic.prompt_cache_stats()
+        return None
+
+    def take_last_prompt_cache_record(self) -> Optional[PromptCacheRecord]:
+        """Récupère le dernier record du prompt cache."""
+        if self._anthropic is not None:
+            return self._anthropic.take_last_prompt_cache_record()
+        return None
+
+    async def send_message(self, request: MessageRequest) -> MessageResponse:
+        """Envoie un message et attend la réponse complète."""
+        if self._anthropic is not None:
+            return await self._anthropic.send_message(request)
+        elif self._openai_compat is not None:
+            return await self._openai_compat.send_message(request)
+        raise ApiError("no provider client configured")
+
+    async def stream_message(self, request: MessageRequest) -> MessageStream:
+        """Envoie un message en mode streaming."""
+        if self._anthropic is not None:
+            return await self._anthropic.stream_message(request)
+        elif self._openai_compat is not None:
+            return await self._openai_compat.stream_message(request)
+        raise ApiError("no provider client configured")
+
+    async def close(self) -> None:
+        """Ferme le client HTTP."""
+        if self._anthropic is not None:
+            await self._anthropic.close()
+        if self._openai_compat is not None:
+            await self._openai_compat.close()
+
+
+def read_xai_base_url() -> str:
+    """Lit la base URL de xAI depuis l'environnement."""
+    from .providers.openai_compat import read_base_url
+
+    return read_base_url(OpenAiCompatConfig.xai())

maestro_core-0.2.0/maestro_core/api/error.py

@@ -0,0 +1,155 @@
+"""Erreurs de l'API — traduit de error.rs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+class ApiError(Exception):
+    """Classe de base pour toutes les erreurs API."""
+
+
+@dataclass
+class MissingCredentialsError(ApiError):
+    """Identifiants manquants pour un provider."""
+
+    provider: str
+    env_vars: tuple[str, ...]
+
+    def __str__(self) -> str:
+        joined = " or ".join(self.env_vars)
+        return (
+            f"missing {self.provider} credentials; export {joined} "
+            f"before calling the {self.provider} API"
+        )
+
+
+class ExpiredOAuthTokenError(ApiError):
+    """Le token OAuth sauvegardé est expiré sans refresh token disponible."""
+
+    def __str__(self) -> str:
+        return "saved OAuth token is expired and no refresh token is available"
+
+
+@dataclass
+class AuthError(ApiError):
+    """Erreur d'authentification."""
+
+    message: str
+
+    def __str__(self) -> str:
+        return f"auth error: {self.message}"
+
+
+@dataclass
+class InvalidApiKeyEnvError(ApiError):
+    """Variable d'environnement de credential invalide."""
+
+    original: Exception
+
+    def __str__(self) -> str:
+        return f"failed to read credential environment variable: {self.original}"
+
+
+@dataclass
+class HttpError(ApiError):
+    """Erreur HTTP (connexion, timeout, etc.)."""
+
+    original: Exception
+
+    def __str__(self) -> str:
+        return f"http error: {self.original}"
+
+
+@dataclass
+class IoError(ApiError):
+    """Erreur I/O."""
+
+    original: Exception
+
+    def __str__(self) -> str:
+        return f"io error: {self.original}"
+
+
+@dataclass
+class JsonError(ApiError):
+    """Erreur de parsing JSON."""
+
+    original: Exception
+
+    def __str__(self) -> str:
+        return f"json error: {self.original}"
+
+
+@dataclass
+class ApiResponseError(ApiError):
+    """Erreur retournée par l'API."""
+
+    status: int
+    error_type: Optional[str] = None
+    message: Optional[str] = None
+    body: str = ""
+    retryable: bool = False
+
+    def __str__(self) -> str:
+        if self.error_type and self.message:
+            return f"api returned {self.status} ({self.error_type}): {self.message}"
+        return f"api returned {self.status}: {self.body}"
+
+    def is_retryable(self) -> bool:
+        return self.retryable
+
+
+@dataclass
+class RetriesExhaustedError(ApiError):
+    """Nombre maximum de retries atteint."""
+
+    attempts: int
+    last_error: ApiError
+
+    def __str__(self) -> str:
+        return f"api failed after {self.attempts} attempts: {self.last_error}"
+
+    def is_retryable(self) -> bool:
+        return _is_retryable(self.last_error)
+
+
+@dataclass
+class InvalidSseFrameError(ApiError):
+    """Frame SSE invalide."""
+
+    detail: str
+
+    def __str__(self) -> str:
+        return f"invalid sse frame: {self.detail}"
+
+
+@dataclass
+class BackoffOverflowError(ApiError):
+    """Dépassement du calcul de backoff exponentiel."""
+
+    attempt: int
+    base_delay_ms: float
+
+    def __str__(self) -> str:
+        return (
+            f"retry backoff overflowed on attempt {self.attempt} "
+            f"with base delay {self.base_delay_ms}ms"
+        )
+
+
+def _is_retryable(error: ApiError) -> bool:
+    """Détermine si une erreur est retryable."""
+    if isinstance(error, HttpError):
+        return True
+    if isinstance(error, ApiResponseError):
+        return error.retryable
+    if isinstance(error, RetriesExhaustedError):
+        return _is_retryable(error.last_error)
+    return False
+
+
+def is_retryable_status(status: int) -> bool:
+    """Vérifie si un code HTTP est retryable."""
+    return status in (408, 409, 429, 500, 502, 503, 504)