botnesia-core 0.1.0__py3-none-any.whl

agent_registry.py

@@ -0,0 +1,170 @@
+"""
+agent_registry.py — Agent Directory + Admin Agent (AI Agent Platform Phase 5).
+
+Katalog deklaratif setiap "digital employee" agent di platform ini (BUKAN
+agent mesin-internal reasoning pipeline seperti Devil's Advocate/Verification/
+Planner/Intent Classifier -- itu komponen reasoning, bukan "karyawan").
+`list_agents()` membaca atribut `skills`/`tools`/`goals` yang SUDAH ADA di
+tiap class lewat import dinamis -- tidak hardcode duplikat supaya tidak
+drift kalau atribut itu berubah. Katalog agent (data proprietary) dan
+`AdminAgent` (fitur agregasi Cloud) berada di modul terpisah dan di-import
+secara guarded, supaya mekanisme registry ini reusable di `botnesia-core`.
+"""
+from __future__ import annotations
+
+import importlib
+from dataclasses import dataclass
+
+from base import BaseAgent
+
+CHAT_PIPELINE = "chat_pipeline"
+AUTHENTICATED_API = "authenticated_api"
+
+# ── Proprietary catalog seam (Open-Core extraction) ─────────────────────────
+# The agent *catalog* (which digital-employee agents exist, their RBAC per
+# category, and the heuristic routing keywords) is BotNesia's proprietary AI
+# Workforce definition. It lives in `agent_directory_data` (Cloud/Enterprise
+# only) so this registry *mechanism* can be reused inside the open
+# `botnesia-core` package without exposing the catalog.
+#
+# In the Cloud/Enterprise deployment `agent_directory_data` is always present,
+# so these names bind to the full catalog and behaviour is byte-identical.
+# In botnesia-core (where that module is absent) they fall back to empty
+# structures: the registry machinery still works, users register their own
+# agents, and no proprietary names are shipped.
+try:
+    from agent_directory_data import (
+        AGENT_DIRECTORY,
+        ORCHESTRATION_EXTRA,
+        AGENT_PERMISSION_BY_CATEGORY,
+        AGENT_CAPABILITY_KEYWORDS,
+    )
+except ImportError:  # pragma: no cover - core-only path (catalog not installed)
+    AGENT_DIRECTORY: list[tuple[str, str, str, str]] = []
+    ORCHESTRATION_EXTRA: list[tuple[str, str, str, str]] = []
+    AGENT_PERMISSION_BY_CATEGORY: dict[str, str | None] = {}
+    AGENT_CAPABILITY_KEYWORDS: dict[str, list[str]] = {}
+
+
+@dataclass
+class OrchestrationAgentSpec:
+    """Deskriptor satu agent yang bisa dipanggil orkestrator internal."""
+    name:         str
+    class_name:   str
+    category:     str
+    module_path:  str
+    permission:   str | None
+    capabilities: list[str]
+
+
+def _overrides_run(cls: type) -> bool:
+    """True bila class benar-benar mengimplementasikan run() sendiri.
+
+    Dasar penemuan DINAMIS: hanya agent dengan run(context) sendiri yang bisa
+    di-orkestrasi seragam via safe_run(). Agent berbasis fungsi-modul (mis.
+    operations/security tanpa run()) otomatis TIDAK terdaftar sampai punya run()
+    — tak perlu daftar hardcode terpisah.
+    """
+    return getattr(cls, "run", None) is not getattr(BaseAgent, "run", None)
+
+
+def build_agent(module_path: str, class_name: str, **kwargs) -> BaseAgent:
+    """Instansiasi agent secara dinamis dari (module_path, class_name).
+
+    Kwarg yang tidak diterima __init__ agent DIBUANG otomatis (kecuali agent
+    memakai **kwargs) supaya config LLM bersama aman dipakai lintas agent yang
+    signature-nya beda-beda — tanpa TypeError.
+    """
+    import inspect
+    module = importlib.import_module(module_path)
+    cls = getattr(module, class_name)
+    try:
+        sig = inspect.signature(cls.__init__)
+        has_var_kw = any(p.kind is inspect.Parameter.VAR_KEYWORD for p in sig.parameters.values())
+        if not has_var_kw:
+            allowed = set(sig.parameters) - {"self"}
+            kwargs = {k: v for k, v in kwargs.items() if k in allowed}
+    except (TypeError, ValueError):
+        pass
+    return cls(**kwargs)
+
+
+def orchestration_agents(
+    *, allowed_permissions: set[str] | None = None
+) -> list[OrchestrationAgentSpec]:
+    """Daftar agent yang boleh dipanggil orkestrator, difilter RBAC.
+
+    Penemuan dinamis: gabung AGENT_DIRECTORY + ORCHESTRATION_EXTRA, sisakan yang
+    override run(), lalu filter berdasarkan permission efektif user. Bila
+    allowed_permissions None → tanpa filter (mis. konteks super-admin/test).
+    """
+    specs: list[OrchestrationAgentSpec] = []
+    seen: set[str] = set()
+    for module_path, class_name, category, _channel in (*AGENT_DIRECTORY, *ORCHESTRATION_EXTRA):
+        if class_name in seen:
+            continue
+        try:
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+        except Exception:
+            continue
+        if not _overrides_run(cls):
+            continue
+        perm = AGENT_PERMISSION_BY_CATEGORY.get(category)
+        if (
+            perm is not None
+            and allowed_permissions is not None
+            and perm not in allowed_permissions
+            and "*" not in allowed_permissions
+        ):
+            continue
+        seen.add(class_name)
+        specs.append(OrchestrationAgentSpec(
+            name=getattr(cls, "name", class_name),
+            class_name=class_name,
+            category=category,
+            module_path=module_path,
+            permission=perm,
+            capabilities=AGENT_CAPABILITY_KEYWORDS.get(category, []),
+        ))
+    return specs
+
+
+def list_agents() -> list[dict]:
+    agents: list[dict] = []
+    for module_path, class_name, category, channel in AGENT_DIRECTORY:
+        try:
+            module = importlib.import_module(module_path)
+            cls = getattr(module, class_name)
+        except Exception:
+            continue
+        agents.append({
+            "name": getattr(cls, "name", class_name),
+            "class_name": class_name,
+            "category": category,
+            "channel": channel,
+            "skills": list(getattr(cls, "skills", [])),
+            "tools": list(getattr(cls, "tools", [])),
+            "goals": list(getattr(cls, "goals", [])),
+        })
+    return agents
+
+
+def get_agent(name: str) -> dict | None:
+    for agent in list_agents():
+        if agent["name"] == name:
+            return agent
+    return None
+
+
+# ── AdminAgent seam (Open-Core extraction) ──────────────────────────────────
+# AdminAgent.platform_overview() aggregates Cloud subsystems (execution log,
+# workforce orchestrator, computer agent, local-agent commands), so the class
+# is a Cloud/Enterprise feature and lives in `agent_admin` (not open-sourced).
+# Re-exported here so `from agent_registry import AdminAgent` keeps working in
+# the Cloud deployment; in botnesia-core the module is absent and AdminAgent is
+# None (the open registry ships without it and without those subsystem names).
+try:
+    from agent_admin import AdminAgent  # noqa: F401
+except ImportError:  # pragma: no cover - core-only path (AdminAgent not installed)
+    AdminAgent = None  # type: ignore[assignment,misc]

ai_providers/__init__.py

@@ -0,0 +1,20 @@
+from ai_providers.types import LLMRequest, LLMResponse, ProviderType, TaskType
+from ai_providers.base import AIProvider
+from ai_providers.gemini import GeminiProvider
+from ai_providers.groq_provider import GroqProvider
+from ai_providers.openrouter import OpenRouterProvider
+from ai_providers.deepseek import DeepSeekProvider
+from ai_providers.router import SmartModelRouter
+
+__all__ = [
+    "LLMRequest",
+    "LLMResponse",
+    "ProviderType",
+    "TaskType",
+    "AIProvider",
+    "GeminiProvider",
+    "GroqProvider",
+    "OpenRouterProvider",
+    "DeepSeekProvider",
+    "SmartModelRouter",
+]

ai_providers/base.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from ai_providers.types import LLMRequest, LLMResponse
+
+
+class AIProvider(ABC):
+    @abstractmethod
+    async def complete(self, request: LLMRequest, *, model: str | None = None) -> LLMResponse:
+        """Non-streaming completion. `model` overrides the provider default."""
+        ...
+
+    @abstractmethod
+    async def stream(self, request: LLMRequest, *, model: str | None = None):
+        """Async generator yielding str chunks."""
+        ...
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """True if provider has a usable API key."""
+        ...
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str: ...
+
+    @property
+    @abstractmethod
+    def default_model(self) -> str: ...

ai_providers/deepseek.py

@@ -0,0 +1,206 @@
+"""
+ai_providers/deepseek.py — DeepSeek provider.
+
+DeepSeek exposes an OpenAI-compatible API at https://api.deepseek.com.
+Models available:
+  deepseek-chat      — DeepSeek-V3, general purpose (fast, cheap, excellent for coding)
+  deepseek-reasoner  — DeepSeek-R1, chain-of-thought reasoning (slower, deeper analysis)
+
+Set DEEPSEEK_API_KEY in .env to activate.  When set, the SmartModelRouter
+uses DeepSeek directly for coding and reasoning tasks — without the OpenRouter
+markup — before falling back to OpenRouter or Groq.
+"""
+import asyncio
+import json as _json
+import logging
+import time
+
+import httpx
+
+from ai_providers.base import AIProvider
+from ai_providers.types import LLMRequest, LLMResponse
+
+logger = logging.getLogger("botnesia.deepseek")
+
+_BASE_URL = "https://api.deepseek.com"
+_RETRYABLE = frozenset({429, 500, 502, 503, 504})
+
+# Default model per task type when routing through DeepSeek directly.
+# CATATAN: task-routing internal ini SENGAJA memakai model DeepSeek yang sudah
+# terbukti (deepseek-chat/deepseek-reasoner) agar pipeline lama tetap stabil.
+# Nama model per-tier "3 otak" yang env-driven ditangani terpisah di
+# deepseek_brain.py (lihat docs/DEEPSEEK_BOTNESIA_BRAIN.md).
+DEEPSEEK_TASK_MODELS: dict = {
+    "coding":          "deepseek-chat",
+    "advanced_coding": "deepseek-chat",
+    "reasoning":       "deepseek-reasoner",
+    "deep_reasoning":  "deepseek-reasoner",
+    "planning":        "deepseek-chat",
+    "document":        "deepseek-chat",
+    "document_analysis": "deepseek-chat",
+}
+
+# Tasks where DeepSeek should NOT be the primary (let Gemini handle these)
+_SKIP_TASKS = frozenset({
+    "chat", "cs", "customer_service", "faq", "sales",
+    "marketing", "hr", "knowledge", "knowledge_search", "internal",
+})
+
+
+def deepseek_model_for_task(task_type: str) -> str | None:
+    """Return DeepSeek model for task, or None if task is better handled elsewhere."""
+    task = (task_type or "chat").lower()
+    if task in _SKIP_TASKS:
+        return None
+    return DEEPSEEK_TASK_MODELS.get(task, "deepseek-chat")
+
+
+def _add_token_usage(model: str, pt: int, ct: int) -> None:
+    try:
+        from agent_observability import add_token_usage
+        add_token_usage(model=model, prompt_tokens=pt, completion_tokens=ct)
+    except Exception:
+        pass
+
+
+class DeepSeekProvider(AIProvider):
+    """
+    DeepSeek direct API — best for coding (deepseek-chat/V3) and
+    chain-of-thought reasoning (deepseek-reasoner/R1).
+
+    Cheaper than routing through OpenRouter because there is no intermediary markup.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = "deepseek-chat",
+        base_url: str = _BASE_URL,
+        max_retries: int = 2,
+        timeout: float = 120.0,
+    ):
+        self.api_key = api_key
+        self.model = model
+        self.base_url = base_url.rstrip("/")
+        self.max_retries = max_retries
+        self.timeout = timeout
+        self._client: httpx.AsyncClient | None = None
+
+    def _get_client(self) -> httpx.AsyncClient:
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=self.timeout)
+        return self._client
+
+    async def aclose(self) -> None:
+        if self._client and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    def is_available(self) -> bool:
+        return bool(self.api_key)
+
+    @property
+    def provider_name(self) -> str:
+        return "deepseek"
+
+    @property
+    def default_model(self) -> str:
+        return self.model
+
+    def _headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.api_key}",
+            "Content-Type": "application/json",
+        }
+
+    async def complete(self, request: LLMRequest, *, model: str | None = None) -> LLMResponse:
+        resolved = model or self.model
+        payload: dict = {
+            "model": resolved,
+            "messages": request.messages,
+            "temperature": request.temperature,
+            "max_tokens": request.max_tokens,
+        }
+        if request.response_format:
+            payload["response_format"] = request.response_format
+
+        client = self._get_client()
+        t0 = time.monotonic()
+        last_exc: Exception | None = None
+        retries = 0
+
+        for attempt in range(self.max_retries + 1):
+            if attempt:
+                await asyncio.sleep(min(2 ** (attempt - 1), 8))
+                retries += 1
+            try:
+                resp = await client.post(
+                    f"{self.base_url}/chat/completions",
+                    json=payload,
+                    headers=self._headers(),
+                )
+                if resp.status_code in _RETRYABLE and attempt < self.max_retries:
+                    last_exc = httpx.HTTPStatusError(
+                        f"status {resp.status_code}", request=resp.request, response=resp
+                    )
+                    continue
+                resp.raise_for_status()
+                data = resp.json() or {}
+                break
+            except (httpx.TimeoutException, httpx.HTTPStatusError) as exc:
+                last_exc = exc
+                if attempt >= self.max_retries:
+                    return LLMResponse(
+                        content="", model=resolved, provider="deepseek",
+                        latency_ms=int((time.monotonic() - t0) * 1000),
+                        error=str(exc), retries=retries,
+                    )
+        else:
+            return LLMResponse(
+                content="", model=resolved, provider="deepseek",
+                latency_ms=int((time.monotonic() - t0) * 1000),
+                error=str(last_exc), retries=retries,
+            )
+
+        latency_ms = int((time.monotonic() - t0) * 1000)
+        usage = data.get("usage") or {}
+        pt = int(usage.get("prompt_tokens") or 0)
+        ct = int(usage.get("completion_tokens") or 0)
+        _add_token_usage(resolved, pt, ct)
+        choices = data.get("choices") or []
+        content = str(((choices[0] or {}).get("message") or {}).get("content") or "").strip()
+        return LLMResponse(
+            content=content, model=resolved, provider="deepseek",
+            prompt_tokens=pt, completion_tokens=ct,
+            latency_ms=latency_ms, retries=retries,
+        )
+
+    async def stream(self, request: LLMRequest, *, model: str | None = None):
+        resolved = model or self.model
+        payload = {
+            "model": resolved,
+            "messages": request.messages,
+            "temperature": request.temperature,
+            "max_tokens": request.max_tokens,
+            "stream": True,
+        }
+        client = self._get_client()
+        async with client.stream(
+            "POST", f"{self.base_url}/chat/completions",
+            json=payload, headers=self._headers(),
+        ) as resp:
+            resp.raise_for_status()
+            async for line in resp.aiter_lines():
+                if not line.startswith("data: "):
+                    continue
+                raw = line[6:].strip()
+                if not raw or raw == "[DONE]":
+                    continue
+                try:
+                    chunk = _json.loads(raw)
+                    delta = ((chunk.get("choices") or [{}])[0].get("delta") or {})
+                    text = delta.get("content")
+                    if text:
+                        yield text
+                except Exception:
+                    continue