kntgraph 0.11.0__py3-none-any.whl

kntgraph/__init__.py

@@ -0,0 +1,33 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+kntgraph -- public package surface.
+
+The ``__version__`` attribute is derived from the
+git tag by ``setuptools_scm`` (ADR-051). The import
+is guarded so a source install without the build
+step (e.g. a CI cache without a full git history)
+returns the explicit ``"0.0.0+unknown"`` fallback
+instead of raising ``AttributeError``.
+
+The fallback uses PEP 440's local-version
+convention (``+unknown``) so consumers can detect
+the case programmatically via
+``version.endswith("+unknown")``.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+try:
+    from kntgraph._version import __version__
+except ImportError:
+    # Source install without ``setuptools_scm``
+    # having run (no git history, no tag). The
+    # version is unknown; downstream code that
+    # relies on a real version should fall back
+    # gracefully rather than crash.
+    __version__ = "0.0.0+unknown"

kntgraph/_optional.py

@@ -0,0 +1,156 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+_optional — single source of truth for lazy/guarded imports
+of optional dependencies.
+
+Background
+----------
+The `kntgraph` package declares several third-party packages
+as optional extras (``falkordb``, ``ollama``, ``gliner2``,
+``fastapi``, ``litellm``, …). The framework's own modules
+should be **importable** even when none of those extras are
+installed, so that:
+
+  - applications that only need the core ECS + EventLog +
+    Memory can install only ``kntgraph`` (no extras) and
+    still ``import kntgraph`` without errors;
+  - tests can stub the optional deps via sys.meta_path
+    blockers without ``ImportError`` at collection time;
+  - the ``agents`` sub-module does not have to
+    transitively pull in ``falkordb`` + ``ollama`` just
+    because someone imports ``kntgraph.agents.roles``.
+
+Each module that uses an optional dep uses one of two
+patterns:
+
+1. **Lazy inside a method** (preferred for runtime-only
+   use, e.g. ``litellm`` in a Tool's ``invoke()``):
+
+   .. code-block:: python
+
+      async def invoke(self, **kwargs):
+          litellm = require_optional("litellm", "kntgraph[llm]")
+          ...
+
+2. **Top-level TYPE_CHECKING-only + eager runtime import
+   behind a guard** (for adapters that are importable but
+   not constructible without the extra, e.g.
+   ``GlinerIntentAdapter``):
+
+   .. code-block:: python
+
+      if TYPE_CHECKING:
+          from gliner2 import GLiNER2  # noqa: F401
+
+      class GlinerIntentAdapter:
+          def __init__(self, ...):
+              GLiNER2 = require_optional(
+                  "gliner2", "kntgraph[gliner]",
+                  purpose="GlinerIntentAdapter",
+              )
+              ...
+
+The helper
+----------
+:func:`require_optional` raises ``ImportError`` with a
+canonical message that always points the user at the
+correct extra to install. Tests assert on the message
+text so accidental rewording is caught.
+
+:func:`try_import` is the non-raising variant — returns
+``None`` instead. Useful for capability checks (e.g. "is
+``fastapi`` available?" before exposing an HTTP route).
+"""
+
+from __future__ import annotations
+
+import importlib
+from types import ModuleType
+from typing import Optional
+
+
+def _format_message(
+    package: str,
+    extra: str,
+    purpose: Optional[str],
+) -> str:
+    """
+    Build the canonical ImportError message. Kept in one
+    place so the wording is consistent across the
+    codebase and tests can pin it.
+    """
+    where = purpose or "this feature"
+    return (
+        f"{where} requires the optional package "
+        f"`{package}`, which is not installed.\n"
+        f"Install it with one of:\n"
+        f"    uv add {extra}\n"
+        f"    pip install {extra}\n"
+        f"See the `[project.optional-dependencies]` table "
+        f"in the package's `pyproject.toml` for the full list "
+        f"of extras."
+    )
+
+
+def require_optional(
+    package: str,
+    extra: str,
+    *,
+    purpose: Optional[str] = None,
+) -> ModuleType:
+    """
+    Import ``package`` or raise ``ImportError`` with a
+    message that points to the right ``extra``.
+
+    Args:
+      package: the PyPI distribution name (the string
+        passed to ``importlib.import_module``).
+      extra: the install extra that provides it, e.g.
+        ``"kntgraph[gliner]"`` or ``"kntgraph[llm]"``.
+      purpose: short human description of what was being
+        attempted, for the error message. Defaults to
+        "this feature".
+
+    Returns:
+      The imported module.
+
+    Raises:
+      ImportError: with the canonical message.
+    """
+    try:
+        return importlib.import_module(package)
+    except ImportError as e:
+        raise ImportError(_format_message(package, extra, purpose)) from e
+
+
+def try_import(
+    package: str,
+    extra: Optional[str] = None,
+) -> Optional[ModuleType]:
+    """
+    Best-effort import — returns ``None`` instead of
+    raising. Useful for capability checks where the
+    caller wants to branch on availability rather than
+    handle an exception.
+
+    Args:
+      package: the PyPI distribution name.
+      extra: kept for API symmetry with
+        :func:`require_optional`; not used in the return
+        path because no error is raised. Provided so
+        callers that switch between the two helpers do
+        not have to drop the argument.
+
+    Returns:
+      The imported module, or ``None`` if not installed.
+    """
+    try:
+        return importlib.import_module(package)
+    except ImportError:
+        return None
+
+
+__all__ = ["require_optional", "try_import"]

kntgraph/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.11.0'
+__version_tuple__ = version_tuple = (0, 11, 0)
+
+__commit_id__ = commit_id = 'g609830e8d'

kntgraph/agents/__init__.py

@@ -0,0 +1,38 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+kntgraph.agents — vertical agents sobre o framework FMH.
+
+Esta package provê:
+
+  - tools/    : adapters concretos (LiteLLM, ...)
+  - roles/    : especializações semânticas que usam tools
+                (Planner, Summarizer, Classifier, ...)
+  - config/   : configuração carregada de env (modelos, budgets, ...)
+  - examples/ : scripts demonstrativos (estudo de APIs)
+
+Convenções
+----------
+
+- **Tool** = 1 capability de I/O. Vive em `tools/`. Registrável
+  no `ToolRegistry`. Implementa o Protocol de
+  `kntgraph.agents.tools.protocol.Tool`.
+- **Role** = especialização semântica. Vive em `roles/`. Não é
+  Tool — usa uma Tool por injeção. Conhece prompt do domínio e
+  schema de saída.
+
+- **agent_id**: a aplicação define. Para NF, o número da NF. Para
+  sessão, "session:<id>". Para Empresa, CNPJ. O framework é
+  agnóstico.
+
+- **idempotency_key**: toda Tool recebe
+  `idempotency_key=str(request.event_id)`. Roles devem
+  repassar essa chave (ou construir uma estável) ao chamar
+  a Tool.
+
+Veja:
+  - ADR-006: separação Tool × Role
+  - ADR-007: LLM via LiteLLM
+"""

kntgraph/agents/config/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""Configuration primitives for ``kntgraph.agents``.
+
+The ``RateLimiter`` is re-exported from
+``kntgraph.resilience.rate_limit`` (the shared
+sliding-window primitive; was previously in the
+standalone ``fmh_core`` package). The ``CostBudget``
+is kntgraph.agents-specific (LLM spending semantics) and
+lives in ``.llm``. ``LLMConfig`` is the main entry point
+for LLM tool configuration.
+"""
+
+from kntgraph.resilience.rate_limit import RateLimiter
+
+from .llm import CostBudget, LLMConfig, load_env
+
+__all__ = ["CostBudget", "LLMConfig", "RateLimiter", "load_env"]

kntgraph/agents/config/llm.py

@@ -0,0 +1,282 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+LLM configuration primitives.
+
+`LLMConfig` carrega o setup do LLM a partir de env vars
+ou dicionário explícito. Encapsula:
+
+  - `default_model`: o modelo primário (ex: "gpt-4o-mini")
+  - `fallback_models`: lista de modelos para tentar em sequência
+                       se o primário falhar (rate limit, 5xx, ...)
+  - `rate_limit_rpm`: requests por minuto (None = sem limite)
+  - `cost_budget_per_hour_usd`: limite de gasto por hora
+                                (None = sem limite)
+  - `timeout_s`: timeout por chamada
+
+`RateLimiter` e `CostBudget` são wrappers async com janela
+deslizante. São úteis para adapters que querem aplicar
+limites em frente ao ``LiteLLMToolWorker`` (e.g. um
+``LiteLLMTransportAdapter`` custom que consulta o budget
+antes de encaminhar a chamada).
+
+Uso típico:
+
+    from kntgraph.agents.config import LLMConfig
+    from kntgraph.agents.tools.llm import LiteLLMToolWorker
+
+    cfg = LLMConfig.from_env()  # lê OPENAI_API_KEY etc
+    worker = LiteLLMToolWorker()  # lê o config do env
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+import time
+from collections import deque
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from kntgraph.infra.config import (
+    BaseSettings,
+    load_dotenv_files,
+    default_dotenv_candidates,
+)
+from kntgraph.resilience.rate_limit import (
+    RateLimiter,
+)
+
+
+def load_env(dotenv_path: Optional[Path] = None) -> bool:
+    """
+    Load environment variables from a `.env` file. Returns
+    True if a file was found and loaded, False otherwise.
+
+    Lookup order:
+      1. `dotenv_path` argument (if given).
+      2. `default_dotenv_candidates()`: `<cwd>/.env`
+         then `~/.env`.
+
+    Variables already in `os.environ` are NOT overwritten
+    (the explicit env wins over the file — `override=False`
+    semantics in `python-dotenv`).
+
+    The implementation is now a thin wrapper around
+    `fmh_core.config.load_dotenv_files`, which is the
+    canonical env-loader for the whole workspace.
+    """
+    if dotenv_path is not None:
+        return bool(load_dotenv_files(dotenv_path))
+    return bool(load_dotenv_files(*default_dotenv_candidates()))
+
+
+# -----------------------------------------------------------------------------
+# LLMConfig
+# -----------------------------------------------------------------------------
+
+
+class _LLMSettings(BaseSettings):
+    """
+    Internal Pydantic-settings wrapper that reads the
+    `KNT_LLM_*` env vars and coerces their types (int /
+    float / CSV tuple) before they land in the frozen
+    `LLMConfig` dataclass.
+
+    The `_env_prefix` is passed positionally at construction
+    by `LLMConfig.from_env(prefix=...)`; Pydantic settings
+    honour the `env_prefix` attribute on `model_config`.
+    """
+
+    model_config = BaseSettings.model_config | {
+        "env_prefix": "KNT_LLM_",
+    }
+
+    def __init__(self, *, _env_prefix: str = "KNT_LLM_", **data) -> None:
+        # `model_config` is class-level; per-instance
+        # overrides are not supported. We accept the prefix
+        # argument for API symmetry with
+        # `LLMConfig.from_env(prefix=...)` but the actual
+        # env-var lookup is governed by the class-level
+        # `env_prefix`. Non-default prefixes (e.g. in
+        # tests) are surfaced as a typed warning so
+        # operators don't get silent wrong-var lookups.
+        if _env_prefix != "KNT_LLM_":
+            import warnings
+
+            warnings.warn(
+                f"_LLMSettings only honours the KNT_LLM_ "
+                f"prefix; requested {_env_prefix!r} is "
+                f"ignored.",
+                UserWarning,
+                stacklevel=2,
+            )
+        super().__init__(**data)
+
+    default_model: Optional[str] = None
+    fallback_models: tuple[str, ...] = ()
+    rate_limit_rpm: Optional[int] = None
+    cost_budget_per_hour_usd: Optional[float] = None
+    timeout_s: float = 30.0
+
+
+@dataclass(frozen=True)
+class LLMConfig:
+    """
+    Configuração imutável para o ``LiteLLMToolWorker`` (ou
+    qualquer outro ``@tool_worker`` que use o transporte
+    LiteLLM).
+
+    Carregue de env via `LLMConfig.from_env()` ou construa
+    explicitamente. O `__post_init__` valida invariantes
+    básicas (modelo não-vazio, fallback é lista, etc).
+    """
+
+    default_model: str = "gpt-4o-mini"
+    fallback_models: tuple[str, ...] = ()
+    rate_limit_rpm: Optional[int] = 60
+    cost_budget_per_hour_usd: Optional[float] = 2.0
+    timeout_s: float = 30.0
+    # LiteLLM drop_params=True: silently drop unsupported params
+    # (e.g. response_format para modelos que não suportam). Útil
+    # em multi-provider onde nem toda feature está disponível.
+    drop_unsupported_params: bool = True
+
+    def __post_init__(self) -> None:
+        if not self.default_model:
+            raise ValueError("default_model must be non-empty")
+        # Coerce fallback_models to tuple regardless of input
+        # (list, tuple, or None — all accepted at construction).
+        if not isinstance(self.fallback_models, tuple):
+            object.__setattr__(self, "fallback_models", tuple(self.fallback_models))
+        if self.rate_limit_rpm is not None and self.rate_limit_rpm <= 0:
+            raise ValueError(f"rate_limit_rpm must be > 0, got {self.rate_limit_rpm}")
+        if (
+            self.cost_budget_per_hour_usd is not None
+            and self.cost_budget_per_hour_usd <= 0
+        ):
+            raise ValueError(
+                f"cost_budget_per_hour_usd must be > 0, "
+                f"got {self.cost_budget_per_hour_usd}"
+            )
+        if self.timeout_s <= 0:
+            raise ValueError(f"timeout_s must be > 0, got {self.timeout_s}")
+
+    @classmethod
+    def from_env(cls, prefix: str = "KNT_LLM_") -> "LLMConfig":
+        """
+        Carrega configuração de variáveis de ambiente.
+
+        Variáveis lidas (todas opcionais):
+          - <prefix>DEFAULT_MODEL
+          - <prefix>FALLBACK_MODELS   (CSV)
+          - <prefix>RATE_LIMIT_RPM
+          - <prefix>COST_BUDGET_USD
+          - <prefix>TIMEOUT_S
+
+        Variáveis de provider (lidas mas não consumidas por
+        LLMConfig — propagadas para LiteLLM):
+          - OLLAMA_API_BASE
+          - OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
+
+        Chamada típica: `LLMConfig.from_env()` no startup.
+
+        Internamente this delegates env-reading to
+        `LLMSettings` (a `BaseSettings` from
+        `kntgraph.infra.config`)
+        so the prefix is honoured and types are coerced
+        through Pydantic; the dataclass `LLMConfig` is the
+        frozen result. We deliberately keep two layers
+        because `LLMConfig` is a frozen dataclass used in
+        hot paths where allocating a Pydantic model would
+        be overkill.
+        """
+        # Confirm provider endpoints are visible to
+        # LiteLLM (which reads them from os.environ). This
+        # is a no-op for the values themselves; it just
+        # documents the contract.
+        for provider_var in (
+            "OLLAMA_API_BASE",
+            "OPENAI_API_BASE",
+            "OPENAI_API_KEY",
+            "ANTHROPIC_API_KEY",
+            "GEMINI_API_KEY",
+        ):
+            _ = os.environ.get(provider_var)
+        env = _LLMSettings(_env_prefix=prefix)
+        return cls(
+            default_model=env.default_model or "gpt-4o-mini",
+            fallback_models=tuple(env.fallback_models or ()),
+            rate_limit_rpm=env.rate_limit_rpm,
+            cost_budget_per_hour_usd=env.cost_budget_per_hour_usd,
+            timeout_s=env.timeout_s,
+        )
+
+    def rate_limiter(self) -> Optional["RateLimiter"]:
+        if self.rate_limit_rpm is None:
+            return None
+        return RateLimiter(rpm=self.rate_limit_rpm)
+
+    def cost_budget(self) -> Optional["CostBudget"]:
+        if self.cost_budget_per_hour_usd is None:
+            return None
+        return CostBudget(per_hour_usd=self.cost_budget_per_hour_usd)
+
+
+# -----------------------------------------------------------------------------
+# CostBudget
+# -----------------------------------------------------------------------------
+
+
+class CostBudget:
+    """
+    Budget de gasto (USD) por hora, sliding-window.
+
+    Mantém uma fila de (timestamp, cost_usd). Antes de cada
+    chamada, o caller pergunta `can_spend(estimated_cost)`.
+    Depois, chama `charge(actual_cost)` para debitar.
+
+    `estimated_cost` permite recusar uma chamada cara antes
+    de incorrer no gasto (ex: prompt muito longo).
+    """
+
+    def __init__(self, per_hour_usd: float) -> None:
+        if per_hour_usd <= 0:
+            raise ValueError(f"per_hour_usd must be > 0, got {per_hour_usd}")
+        self._per_hour = per_hour_usd
+        self._window_s = 3600.0
+        self._entries: deque[tuple[float, float]] = deque()
+        self._lock = asyncio.Lock()
+
+    @property
+    def per_hour_usd(self) -> float:
+        return self._per_hour
+
+    async def _spent_in_window(self) -> float:
+        now = time.monotonic()
+        while self._entries and (now - self._entries[0][0] > self._window_s):
+            self._entries.popleft()
+        return sum(c for _, c in self._entries)
+
+    async def can_spend(self, estimated_cost_usd: float) -> bool:
+        if estimated_cost_usd < 0:
+            raise ValueError(
+                f"estimated_cost_usd must be >= 0, got {estimated_cost_usd}"
+            )
+        async with self._lock:
+            spent = await self._spent_in_window()
+            return spent + estimated_cost_usd <= self._per_hour
+
+    async def charge(self, cost_usd: float) -> None:
+        if cost_usd < 0:
+            raise ValueError(f"cost_usd must be >= 0, got {cost_usd}")
+        async with self._lock:
+            self._entries.append((time.monotonic(), cost_usd))
+
+    async def remaining_usd(self) -> float:
+        async with self._lock:
+            spent = await self._spent_in_window()
+            return max(0.0, self._per_hour - spent)

kntgraph/agents/knowledge/__init__.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 kinetgraph
+#
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+kntgraph.agents.knowledge -- Vertical knowledge-graph adapters.
+
+Re-exports the :class:`SolutionProjector` (the FalkorDB
+adapter for the Solution sub-graph, ADR-010 §3). The
+framework exposes only the generic knowledge primitives
+(FalkorDB client, embedding provider Protocol); the
+Solution-specific adapter lives here because the schema
+is a vertical product choice.
+"""
+
+from kntgraph.agents.knowledge.solution_projector import SolutionProjector
+
+
+__all__ = ["SolutionProjector"]