agentx-kit 0.2.0__py3-none-any.whl

agentx/observability.py

@@ -0,0 +1,103 @@
+"""Observability: OpenTelemetry GenAI tracing with pluggable backends.
+
+Follows the 2025–2026 convergence on OpenTelemetry `gen_ai.*` semantic
+conventions. Everything is optional and lazy — if the extras aren't installed,
+calls are graceful no-ops. Telemetry honours an explicit opt-out.
+
+Usage in an app::
+
+    from agentx.observability import setup_tracing, get_callbacks
+    setup_tracing("my-service")                     # instrument once at startup
+    llm.invoke(msg, config={"callbacks": get_callbacks()})
+
+Env:
+  AGENTX_TELEMETRY=false          # global kill-switch (also OTEL_SDK_DISABLED=true)
+  OTEL_EXPORTER_OTLP_ENDPOINT=... # send OTel spans here (Phoenix/Tempo/etc.)
+  LANGFUSE_PUBLIC_KEY / LANGFUSE_SECRET_KEY [/ LANGFUSE_HOST]
+"""
+from __future__ import annotations
+
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+_INSTRUMENTED = False
+
+
+def telemetry_enabled() -> bool:
+    """True unless explicitly disabled via AGENTX_TELEMETRY or OTEL_SDK_DISABLED."""
+    if os.getenv("OTEL_SDK_DISABLED", "").lower() == "true":
+        return False
+    return os.getenv("AGENTX_TELEMETRY", "true").lower() not in ("false", "0", "no")
+
+
+def setup_tracing(service_name: str = "agentx") -> bool:
+    """Instrument LangChain with OpenTelemetry (OpenInference). Returns success.
+
+    No-op (returns False) if telemetry is disabled or the optional extras
+    (`agentx-kit[observability]`) aren't installed.
+    """
+    global _INSTRUMENTED
+    if _INSTRUMENTED:
+        return True
+    if not telemetry_enabled():
+        logger.info("Telemetry disabled; skipping tracing setup.")
+        return False
+    try:
+        from openinference.instrumentation.langchain import LangChainInstrumentor
+        from opentelemetry import trace
+        from opentelemetry.sdk.resources import Resource
+        from opentelemetry.sdk.trace import TracerProvider
+        from opentelemetry.sdk.trace.export import BatchSpanProcessor
+    except ImportError:
+        logger.info("OpenTelemetry extras not installed; run `pip install 'agentx-kit[observability]'`.")
+        return False
+
+    try:
+        provider = TracerProvider(resource=Resource.create({"service.name": service_name}))
+        endpoint = os.getenv("OTEL_EXPORTER_OTLP_ENDPOINT")
+        if endpoint:
+            from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+
+            provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+        else:
+            from opentelemetry.sdk.trace.export import ConsoleSpanExporter
+
+            provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+        trace.set_tracer_provider(provider)
+        LangChainInstrumentor().instrument()
+        _INSTRUMENTED = True
+        logger.info("OpenTelemetry tracing enabled for '%s' (endpoint=%s).", service_name, endpoint or "console")
+        return True
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Tracing setup failed: %s", exc)
+        return False
+
+
+def langfuse_callbacks() -> list:
+    """Return [Langfuse CallbackHandler] if Langfuse is installed + configured."""
+    if not telemetry_enabled():
+        return []
+    if not (os.getenv("LANGFUSE_PUBLIC_KEY") and os.getenv("LANGFUSE_SECRET_KEY")):
+        return []
+    try:
+        from langfuse.langchain import CallbackHandler
+
+        return [CallbackHandler()]
+    except ImportError:
+        try:
+            from langfuse.callback import CallbackHandler  # older layout
+
+            return [CallbackHandler()]
+        except ImportError:
+            logger.info("Langfuse not installed; `pip install langfuse` to enable.")
+            return []
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Langfuse callback init failed: %s", exc)
+        return []
+
+
+def get_callbacks() -> list:
+    """LangChain callbacks to pass via ``config={'callbacks': get_callbacks()}``."""
+    return langfuse_callbacks()

agentx/prompts/__init__.py

@@ -0,0 +1,8 @@
+"""Reusable, override-able prompt templates for agents."""
+from .templates import (
+    AGENT_SYSTEM_PROMPT,
+    RAG_SYSTEM_PROMPT,
+    render_agent_system,
+)
+
+__all__ = ["AGENT_SYSTEM_PROMPT", "RAG_SYSTEM_PROMPT", "render_agent_system"]

agentx/prompts/templates.py

@@ -0,0 +1,40 @@
+"""Prompt templates and a small renderer.
+
+Kept as plain strings (not framework-specific) so they work with both LangChain
+and CrewAI. ``render_agent_system`` lets callers inject role, goal and optional
+skills/RAG guidance without pulling in a templating engine at runtime.
+"""
+from __future__ import annotations
+
+AGENT_SYSTEM_PROMPT = (
+    "You are {role}.\n"
+    "Your goal: {goal}\n"
+    "Guidelines:\n"
+    "- Be precise, concise, and grounded in available context/tools.\n"
+    "- If you are unsure, say so rather than inventing facts.\n"
+    "- Prefer using your tools over guessing.\n"
+)
+
+RAG_SYSTEM_PROMPT = (
+    "Answer the user using ONLY the retrieved context below. "
+    "If the answer is not in the context, say you don't know.\n\n"
+    "Context:\n{context}\n"
+)
+
+_SKILLS_BLOCK = "\nApply these skills/standards:\n{skills}\n"
+_RAG_BLOCK = "\nYou have a knowledge base; retrieve before answering when relevant.\n"
+
+
+def render_agent_system(
+    role: str,
+    goal: str,
+    skills: str | None = None,
+    with_rag: bool = False,
+) -> str:
+    """Render an agent system prompt with optional skills + RAG hints."""
+    out = AGENT_SYSTEM_PROMPT.format(role=role, goal=goal)
+    if skills:
+        out += _SKILLS_BLOCK.format(skills=skills)
+    if with_rag:
+        out += _RAG_BLOCK
+    return out

agentx/providers/__init__.py

@@ -0,0 +1,15 @@
+"""Provider subsystem: a registry + factory for building LLM clients."""
+from .base import ProviderError, ProviderSpec
+from .factory import get_chat_model, get_crewai_llm, list_providers
+from .registry import all_specs, canonical_ids, get_spec
+
+__all__ = [
+    "ProviderError",
+    "ProviderSpec",
+    "get_chat_model",
+    "get_crewai_llm",
+    "list_providers",
+    "all_specs",
+    "canonical_ids",
+    "get_spec",
+]

agentx/providers/base.py

@@ -0,0 +1,50 @@
+"""Provider abstractions: ``ProviderSpec`` and shared helpers.
+
+A ``ProviderSpec`` is pure metadata + two builder callables. Builders import
+their provider SDK lazily so installing one extra never forces the others.
+"""
+from __future__ import annotations
+
+import importlib
+import os
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+
+class ProviderError(RuntimeError):
+    """Raised when a provider cannot be constructed (missing package / creds)."""
+
+
+def require(module: str, extra: str) -> Any:
+    """Import ``module`` or raise a helpful, actionable error naming the extra."""
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:  # pragma: no cover - exercised via factory error path
+        raise ProviderError(
+            f"Missing dependency '{module}'. Install it with:\n"
+            f"    uv pip install 'agentx-kit[{extra}]'\n"
+            f"(or: pip install {module})"
+        ) from exc
+
+
+def warn_missing_env(spec: "ProviderSpec") -> list[str]:
+    """Return the subset of a provider's env vars that are not set."""
+    return [v for v in spec.env_vars if not os.getenv(v)]
+
+
+# A builder takes (model, **kwargs) and returns a LangChain BaseChatModel.
+ChatBuilder = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class ProviderSpec:
+    id: str
+    label: str
+    extra: str                      # pip extra: agentx-kit[<extra>]
+    packages: tuple[str, ...]       # importable module names the extra provides
+    default_model: str
+    env_vars: tuple[str, ...]       # standard credential env vars (informational)
+    crewai_prefix: str              # LiteLLM/CrewAI model prefix, e.g. "openrouter/"
+    build_chat: ChatBuilder         # () -> langchain BaseChatModel
+    notes: str = ""
+    aliases: tuple[str, ...] = field(default_factory=tuple)

agentx/providers/factory.py

@@ -0,0 +1,71 @@
+"""Public factory functions for building LLM clients across frameworks."""
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..config import get_settings
+from .base import ProviderError, ProviderSpec, warn_missing_env
+from .registry import all_specs, get_spec
+
+logger = logging.getLogger(__name__)
+
+
+def list_providers() -> list[ProviderSpec]:
+    """Return all registered provider specs (canonical, no aliases)."""
+    return all_specs()
+
+
+def get_chat_model(provider: str | None = None, model: str | None = None, **kwargs: Any):
+    """Build a LangChain ``BaseChatModel`` for any supported provider.
+
+    Args:
+        provider: provider id (e.g. "openai", "bedrock", "openrouter"). Defaults
+            to ``AGENTX_PROVIDER`` / settings.
+        model: model id; falls back to the provider's default.
+        **kwargs: passed through to the underlying chat class (temperature, etc.).
+    """
+    s = get_settings()
+    provider = provider or s.default_provider
+    spec = get_spec(provider)
+    model = model or s.default_model or spec.default_model
+
+    missing = warn_missing_env(spec)
+    if missing:
+        logger.warning(
+            "Provider '%s' is missing env vars: %s. The call may fail to authenticate.",
+            spec.id, ", ".join(missing),
+        )
+    return spec.build_chat(model, **kwargs)
+
+
+def get_crewai_llm(provider: str | None = None, model: str | None = None, **kwargs: Any):
+    """Build a CrewAI ``LLM`` for any supported provider.
+
+    CrewAI routes through LiteLLM, so we map the provider to its LiteLLM prefix
+    (e.g. ``openrouter/`` , ``bedrock/`` , ``gemini/``) and pass base_url/api_key
+    where relevant. Requires ``agentx-kit[crewai]``.
+    """
+    s = get_settings()
+    provider = provider or s.default_provider
+    spec = get_spec(provider)
+    model = model or s.default_model or spec.default_model
+
+    try:
+        from crewai import LLM  # type: ignore
+    except ImportError as exc:
+        raise ProviderError(
+            "CrewAI is not installed. Install it with:\n"
+            "    uv pip install 'agentx-kit[crewai]'"
+        ) from exc
+
+    # Avoid double-prefixing if the caller already passed e.g. "openrouter/...".
+    litellm_model = model if "/" in model and model.startswith(spec.crewai_prefix) else f"{spec.crewai_prefix}{model}"
+
+    params: dict[str, Any] = {"model": litellm_model, "temperature": kwargs.pop("temperature", s.temperature)}
+    if spec.id == "openrouter":
+        params["base_url"] = s.openrouter_base_url
+    if spec.id == "ollama":
+        params["base_url"] = s.ollama_base_url
+    params.update(kwargs)
+    return LLM(**params)

agentx/providers/registry.py

@@ -0,0 +1,165 @@
+"""The provider registry — every supported LLM backend in one place.
+
+Each entry's ``build_chat`` returns a LangChain ``BaseChatModel``. Builders pull
+generic defaults (temperature, timeout) from settings and accept ``**kwargs``
+overrides; provider credentials come from each SDK's standard env vars.
+"""
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from ..config import get_settings
+from .base import ProviderSpec, require
+
+
+def _common(kwargs: dict) -> dict:
+    s = get_settings()
+    kwargs.setdefault("temperature", s.temperature)
+    return kwargs
+
+
+# --------------------------------------------------------------------------- #
+# Builders (lazy imports inside each)
+# --------------------------------------------------------------------------- #
+def _build_openai(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_openai", "openai")
+    return mod.ChatOpenAI(model=model or "gpt-4o-mini", **_common(kwargs))
+
+
+def _build_azure(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_openai", "azure")
+    kwargs.setdefault("api_version", os.getenv("AZURE_OPENAI_API_VERSION", "2024-06-01"))
+    kwargs.setdefault("azure_endpoint", os.getenv("AZURE_OPENAI_ENDPOINT"))
+    # On Azure, `model` is the *deployment* name.
+    return mod.AzureChatOpenAI(azure_deployment=model or os.getenv("AZURE_OPENAI_DEPLOYMENT", "gpt-4o"), **_common(kwargs))
+
+
+def _build_openrouter(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_openai", "openrouter")
+    s = get_settings()
+    kwargs.setdefault("base_url", s.openrouter_base_url)
+    kwargs.setdefault("api_key", os.getenv("OPENROUTER_API_KEY"))
+    return mod.ChatOpenAI(model=model or "openai/gpt-4o-mini", **_common(kwargs))
+
+
+def _build_anthropic(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_anthropic", "anthropic")
+    return mod.ChatAnthropic(model=model or "claude-3-5-sonnet-latest", **_common(kwargs))
+
+
+def _build_gemini(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_google_genai", "google")
+    return mod.ChatGoogleGenerativeAI(model=model or "gemini-1.5-flash", **_common(kwargs))
+
+
+def _build_vertex(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_google_vertexai", "vertex")
+    kwargs.setdefault("project", os.getenv("GOOGLE_CLOUD_PROJECT"))
+    kwargs.setdefault("location", os.getenv("GOOGLE_CLOUD_LOCATION", "us-central1"))
+    return mod.ChatVertexAI(model=model or "gemini-1.5-flash", **_common(kwargs))
+
+
+def _build_bedrock(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_aws", "bedrock")
+    kwargs.setdefault("region_name", os.getenv("AWS_REGION", os.getenv("AWS_DEFAULT_REGION", "us-east-1")))
+    return mod.ChatBedrockConverse(model=model or "anthropic.claude-3-5-sonnet-20240620-v1:0", **_common(kwargs))
+
+
+def _build_groq(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_groq", "groq")
+    return mod.ChatGroq(model=model or "llama-3.3-70b-versatile", **_common(kwargs))
+
+
+def _build_ollama(model: str | None = None, **kwargs: Any):
+    mod = require("langchain_ollama", "ollama")
+    kwargs.setdefault("base_url", get_settings().ollama_base_url)
+    return mod.ChatOllama(model=model or "llama3.2", **_common(kwargs))
+
+
+# --------------------------------------------------------------------------- #
+# Registry
+# --------------------------------------------------------------------------- #
+_REGISTRY: dict[str, ProviderSpec] = {}
+
+
+def _register(spec: ProviderSpec) -> None:
+    _REGISTRY[spec.id] = spec
+    for alias in spec.aliases:
+        _REGISTRY[alias] = spec
+
+
+_register(ProviderSpec(
+    id="openai", label="OpenAI", extra="openai", packages=("langchain_openai",),
+    default_model="gpt-4o-mini", env_vars=("OPENAI_API_KEY",), crewai_prefix="openai/",
+    build_chat=_build_openai,
+))
+_register(ProviderSpec(
+    id="azure", label="Azure OpenAI", extra="azure", packages=("langchain_openai",),
+    default_model="gpt-4o", env_vars=("AZURE_OPENAI_API_KEY", "AZURE_OPENAI_ENDPOINT"),
+    crewai_prefix="azure/", build_chat=_build_azure, aliases=("azure_openai",),
+    notes="`model` is your Azure *deployment* name; set AZURE_OPENAI_API_VERSION/ENDPOINT.",
+))
+_register(ProviderSpec(
+    id="openrouter", label="OpenRouter", extra="openrouter", packages=("langchain_openai",),
+    default_model="openai/gpt-4o-mini", env_vars=("OPENROUTER_API_KEY",),
+    crewai_prefix="openrouter/", build_chat=_build_openrouter,
+    notes="OpenAI-compatible gateway to 200+ models; model id like 'anthropic/claude-3.5-sonnet'.",
+))
+_register(ProviderSpec(
+    id="anthropic", label="Anthropic (Claude)", extra="anthropic", packages=("langchain_anthropic",),
+    default_model="claude-3-5-sonnet-latest", env_vars=("ANTHROPIC_API_KEY",),
+    crewai_prefix="anthropic/", build_chat=_build_anthropic, aliases=("claude",),
+))
+_register(ProviderSpec(
+    id="gemini", label="Google Gemini (AI Studio)", extra="google",
+    packages=("langchain_google_genai",), default_model="gemini-1.5-flash",
+    env_vars=("GOOGLE_API_KEY",), crewai_prefix="gemini/", build_chat=_build_gemini,
+    aliases=("google", "google_genai"),
+))
+_register(ProviderSpec(
+    id="vertexai", label="Google Vertex AI", extra="vertex",
+    packages=("langchain_google_vertexai",), default_model="gemini-1.5-flash",
+    env_vars=("GOOGLE_CLOUD_PROJECT", "GOOGLE_APPLICATION_CREDENTIALS"),
+    crewai_prefix="vertex_ai/", build_chat=_build_vertex, aliases=("vertex",),
+    notes="Uses ADC / service-account; set GOOGLE_CLOUD_PROJECT and credentials.",
+))
+_register(ProviderSpec(
+    id="bedrock", label="Amazon Bedrock", extra="bedrock", packages=("langchain_aws",),
+    default_model="anthropic.claude-3-5-sonnet-20240620-v1:0",
+    env_vars=("AWS_ACCESS_KEY_ID", "AWS_SECRET_ACCESS_KEY"), crewai_prefix="bedrock/",
+    build_chat=_build_bedrock, aliases=("aws",),
+    notes="Uses standard AWS credential chain; set AWS_REGION.",
+))
+_register(ProviderSpec(
+    id="groq", label="Groq", extra="groq", packages=("langchain_groq",),
+    default_model="llama-3.3-70b-versatile", env_vars=("GROQ_API_KEY",),
+    crewai_prefix="groq/", build_chat=_build_groq,
+))
+_register(ProviderSpec(
+    id="ollama", label="Ollama (local)", extra="ollama", packages=("langchain_ollama",),
+    default_model="llama3.2", env_vars=(), crewai_prefix="ollama/",
+    build_chat=_build_ollama, notes="Runs locally; no API key. `ollama serve` + pull a model.",
+))
+
+
+def get_spec(provider: str) -> ProviderSpec:
+    key = (provider or "").strip().lower()
+    if key not in _REGISTRY:
+        raise KeyError(
+            f"Unknown provider '{provider}'. Known: {', '.join(sorted(canonical_ids()))}"
+        )
+    return _REGISTRY[key]
+
+
+def canonical_ids() -> list[str]:
+    """Distinct canonical provider ids (excludes aliases), in registration order."""
+    seen: list[str] = []
+    for spec in _REGISTRY.values():
+        if spec.id not in seen:
+            seen.append(spec.id)
+    return seen
+
+
+def all_specs() -> list[ProviderSpec]:
+    return [_REGISTRY[i] for i in canonical_ids()]

agentx/rag/__init__.py

@@ -0,0 +1,8 @@
+"""RAG: chunk documents, index them, retrieve relevant passages.
+
+Uses Chroma when ``agentx-kit[rag]`` is installed; otherwise falls back to a
+dependency-free in-memory keyword retriever so RAG works out of the box.
+"""
+from .pipeline import RagIndex, build_index_from_texts, make_retriever_tool
+
+__all__ = ["RagIndex", "build_index_from_texts", "make_retriever_tool"]

agentx/rag/pipeline.py

@@ -0,0 +1,121 @@
+"""A small, swappable RAG pipeline.
+
+Strategy:
+  * Split text into chunks (LangChain splitter if available, else a simple splitter).
+  * Index with Chroma + embeddings when ``[rag]`` is installed.
+  * Otherwise fall back to an in-memory keyword retriever (no deps), so the
+    generated project runs immediately and can be upgraded later.
+"""
+from __future__ import annotations
+
+import logging
+import re
+from collections import Counter
+from dataclasses import dataclass, field
+
+logger = logging.getLogger(__name__)
+
+
+def _split(text: str, chunk_size: int = 800, overlap: int = 120) -> list[str]:
+    try:
+        from langchain_text_splitters import RecursiveCharacterTextSplitter
+
+        splitter = RecursiveCharacterTextSplitter(chunk_size=chunk_size, chunk_overlap=overlap)
+        return [c for c in splitter.split_text(text) if c.strip()]
+    except ImportError:
+        chunks, start = [], 0
+        while start < len(text):
+            chunks.append(text[start:start + chunk_size])
+            start += chunk_size - overlap
+        return [c for c in chunks if c.strip()]
+
+
+_TOKEN = re.compile(r"[a-z0-9]+")
+
+
+def _tokens(s: str) -> list[str]:
+    return [t for t in _TOKEN.findall(s.lower()) if len(t) > 1]
+
+
+@dataclass
+class RagIndex:
+    """Holds chunks and answers similarity queries.
+
+    If a vector store is available it is used; otherwise a keyword scorer ranks
+    chunks. The public ``search`` API is identical either way.
+    """
+
+    chunks: list[str] = field(default_factory=list)
+    _store: object | None = None
+
+    def search(self, query: str, k: int = 4) -> list[str]:
+        if self._store is not None:
+            try:
+                docs = self._store.similarity_search(query, k=k)
+                return [d.page_content for d in docs]
+            except Exception as exc:  # noqa: BLE001
+                logger.warning("Vector search failed, falling back to keyword: %s", exc)
+        # Keyword fallback.
+        if not self.chunks:
+            return []
+        q = Counter(_tokens(query))
+        scored = [(sum(_tokens(c).count(t) for t in q), c) for c in self.chunks]
+        scored.sort(key=lambda x: x[0], reverse=True)
+        top = [c for s, c in scored if s > 0][:k]
+        return top or self.chunks[:k]
+
+    def context(self, query: str, k: int = 4) -> str:
+        return "\n---\n".join(self.search(query, k))
+
+
+def build_index_from_texts(texts: list[str], persist_dir: str | None = None, embeddings=None) -> RagIndex:
+    """Build a ``RagIndex`` from raw texts; uses Chroma if installed."""
+    chunks: list[str] = []
+    for t in texts:
+        chunks.extend(_split(t))
+
+    store = None
+    try:
+        from langchain_chroma import Chroma  # type: ignore
+
+        if embeddings is None:
+            from langchain_core.embeddings import Embeddings  # noqa: F401
+            embeddings = _default_embeddings()
+        if embeddings is not None:
+            store = Chroma.from_texts(chunks, embedding=embeddings, persist_directory=persist_dir)
+    except ImportError:
+        logger.info("Chroma not installed; using in-memory keyword retriever. Install 'agentx-kit[rag]' to upgrade.")
+    except Exception as exc:  # noqa: BLE001
+        logger.warning("Vector index build failed (%s); using keyword retriever.", exc)
+
+    return RagIndex(chunks=chunks, _store=store)
+
+
+def _default_embeddings():
+    """Best-effort embeddings: try a local/OpenAI embedder, else None (keyword mode)."""
+    try:
+        from langchain_openai import OpenAIEmbeddings  # type: ignore
+        import os
+
+        if os.getenv("OPENAI_API_KEY"):
+            return OpenAIEmbeddings(model="text-embedding-3-small")
+    except ImportError:
+        pass
+    try:
+        from langchain_ollama import OllamaEmbeddings  # type: ignore
+
+        return OllamaEmbeddings(model="nomic-embed-text")
+    except ImportError:
+        return None
+
+
+def make_retriever_tool(index: RagIndex):
+    """Expose a ``RagIndex`` as a LangChain retrieval ``@tool``."""
+    from langchain_core.tools import tool
+
+    @tool
+    def knowledge_base(query: str) -> str:
+        """Search the project's knowledge base and return relevant passages."""
+        return index.context(query)
+
+    return knowledge_base