agentify-core 0.1.0__py3-none-any.whl

agentify/core/callbacks.py

@@ -0,0 +1,73 @@
+from typing import Any, Dict, List, Optional, Protocol
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class AgentCallbackHandler(Protocol):
+    """Interface for agent callbacks to allow observability and side-effects."""
+
+    def on_agent_start(self, agent_name: str, user_input: str) -> None:
+        """Called when the agent starts processing a request."""
+        ...
+
+    def on_agent_finish(self, agent_name: str, response: str) -> None:
+        """Called when the agent finishes processing a request."""
+        ...
+
+    def on_tool_start(self, tool_name: str, args: Dict[str, Any]) -> None:
+        """Called when a tool is about to be executed."""
+        ...
+
+    def on_tool_finish(self, tool_name: str, output: str) -> None:
+        """Called when a tool finishes execution."""
+        ...
+
+    def on_llm_start(self, model_name: str, messages: List[Dict[str, Any]]) -> None:
+        """Called when the LLM is about to be called."""
+        ...
+
+    def on_llm_new_token(self, token: str) -> None:
+        """Called when a new token is generated (streaming only)."""
+        ...
+
+    def on_llm_end(self, response: Any) -> None:
+        """Called when the LLM finishes generating a response."""
+        ...
+
+    def on_error(self, error: Exception, context: str) -> None:
+        """Called when an error occurs."""
+        ...
+
+
+class LoggingCallbackHandler(AgentCallbackHandler):
+    """Simple callback handler that logs events using the standard logging module."""
+
+    def __init__(self, logger_instance: Optional[logging.Logger] = None):
+        self.logger = logger_instance or logger
+
+    def on_agent_start(self, agent_name: str, user_input: str) -> None:
+        self.logger.info(f"Agent '{agent_name}' started. Input: {user_input[:100]}...")
+
+    def on_agent_finish(self, agent_name: str, response: str) -> None:
+        self.logger.info(
+            f"Agent '{agent_name}' finished. Response: {response[:100]}..."
+        )
+
+    def on_tool_start(self, tool_name: str, args: Dict[str, Any]) -> None:
+        self.logger.info(f"Tool '{tool_name}' started. Args: {args}")
+
+    def on_tool_finish(self, tool_name: str, output: str) -> None:
+        self.logger.info(f"Tool '{tool_name}' finished. Output: {output[:100]}...")
+
+    def on_llm_start(self, model_name: str, messages: List[Dict[str, Any]]) -> None:
+        self.logger.debug(f"LLM '{model_name}' started. Messages: {len(messages)}")
+
+    def on_llm_new_token(self, token: str) -> None:
+        pass  # Too verbose for standard logging
+
+    def on_llm_end(self, response: Any) -> None:
+        self.logger.debug("LLM finished.")
+
+    def on_error(self, error: Exception, context: str) -> None:
+        self.logger.error(f"Error in {context}: {error}", exc_info=True)

agentify/core/config.py

@@ -0,0 +1,30 @@
+from dataclasses import dataclass
+from typing import Dict, Any, Optional
+
+
+@dataclass
+class ImageConfig:
+    """Configuration for image processing."""
+    max_side_px: int = 1024
+    quality: int = 90
+    detail: str = "auto"
+
+
+@dataclass
+class AgentConfig:
+    """Configuration for the agent's behavior and model parameters."""
+    name: str
+    system_prompt: str
+    provider: str
+    model_name: str
+    temperature: float = 0.5
+    timeout: int = 60
+    stream: bool = False
+    max_retries: int = 3
+    max_tool_iter: int = 5
+    client_config_override: Optional[Dict[str, Any]] = None
+    callbacks: list = None
+
+    def __post_init__(self):
+        if self.callbacks is None:
+            self.callbacks = []

agentify/core/tool.py

@@ -0,0 +1,30 @@
+import json
+from typing import Dict, Any, Callable
+from dataclasses import dataclass
+
+
+@dataclass(slots=True)
+class Tool:
+    """Wrapper for binding JSON-schema with its Python function."""
+
+    schema: Dict[str, Any]
+    func: Callable[..., Any]
+
+    def __post_init__(self) -> None:
+        if "name" not in self.schema:
+            raise ValueError("Tool schema must include 'name'")
+
+    @property
+    def name(self) -> str:
+        return self.schema["name"]
+
+    def __call__(self, **kwargs: Any) -> str:
+        """Executes the function and returns JSON or string; captures generic errors."""
+        try:
+            result = self.func(**kwargs)
+        except Exception as exc:  # noqa: BLE001
+            return json.dumps({"error": str(exc)}, ensure_ascii=False)
+
+        if isinstance(result, (dict, list)):
+            return json.dumps(result, ensure_ascii=False)
+        return str(result)

agentify/extensions/prompts/__init__.py

@@ -0,0 +1,3 @@
+from agentify.extensions.prompts.assistant import assistant_prompt
+
+__all__ = ["assistant_prompt"]

agentify/extensions/prompts/assistant.py

@@ -0,0 +1,16 @@
+assistant_prompt = """
+You are an AI assistant with access to tools whose goal is to resolve user queries in a professional, accurate, and friendly manner. Follow these guidelines:
+
+1. Response Style
+   - Respond clearly and concisely, using natural punctuation.
+   - Do not include production notes, annotations, or internal instructions.
+
+2. User Interaction
+   - Maintain a professional, helpful, and empathetic tone.
+   - Ask clarifying questions if you need more context or details.
+   - Acknowledge and value the user's effort.
+
+3. Tool Usage
+   - Detect when it is relevant to use the available tools and do so efficiently.
+   - Integrate the results of the tools into your final explanation.
+"""

agentify/extensions/tools/__init__.py

@@ -0,0 +1,9 @@
+from agentify.extensions.tools.time import get_current_time_tool
+from agentify.extensions.tools.calculator import calculate_expression_tool
+from agentify.extensions.tools.weather import get_weather_tool
+
+__all__ = [
+    "get_current_time_tool",
+    "calculate_expression_tool",
+    "get_weather_tool",
+]

agentify/extensions/tools/calculator.py

@@ -0,0 +1,56 @@
+from agentify.core.tool import Tool
+import ast
+import operator as op
+
+
+calculate_expression_schema = {
+    "name": "calculate_expression",
+    "description": "Evalúa una expresión matemática segura y devuelve el resultado.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "expression": {
+                "type": "string",
+                "description": "Expresión matemática a calcular, por ejemplo '2 + 2 * (3 - 1)'.",
+            }
+        },
+        "required": ["expression"],
+    },
+}
+
+
+_allowed_ops = {
+    ast.Add: op.add,
+    ast.Sub: op.sub,
+    ast.Mult: op.mul,
+    ast.Div: op.truediv,
+    ast.Pow: op.pow,
+    ast.Mod: op.mod,
+    ast.UAdd: op.pos,
+    ast.USub: op.neg,
+}
+
+
+def _eval_node(node):
+    if isinstance(node, ast.Num):
+        return node.n
+    if isinstance(node, ast.BinOp):
+        left = _eval_node(node.left)
+        right = _eval_node(node.right)
+        return _allowed_ops[type(node.op)](left, right)
+    if isinstance(node, ast.UnaryOp):
+        operand = _eval_node(node.operand)
+        return _allowed_ops[type(node.op)](operand)
+    raise ValueError(f"Operador no permitido: {node}")
+
+
+def calculate_expression(expression: str):
+    try:
+        tree = ast.parse(expression, mode="eval").body
+        result = _eval_node(tree)
+        return {"result": result}
+    except Exception as e:
+        return {"error": f"Expresión inválida: {e}"}
+
+
+calculate_expression_tool = Tool(calculate_expression_schema, calculate_expression)

agentify/extensions/tools/time.py

@@ -0,0 +1,21 @@
+from agentify.core.tool import Tool
+import datetime
+
+
+get_current_time_schema = {
+    "name": "get_current_time",
+    "description": "Devuelve la hora y fecha actual en formato ISO 8601.",
+    "parameters": {
+        "type": "object",
+        "properties": {},
+        "required": [],
+    },
+}
+
+
+def get_current_time():
+    now = datetime.datetime.now().astimezone().isoformat()
+    return {"current_time": now}
+
+
+get_current_time_tool = Tool(get_current_time_schema, get_current_time)

agentify/extensions/tools/weather.py

@@ -0,0 +1,51 @@
+from agentify.core.tool import Tool
+import os
+import requests
+from dotenv import load_dotenv
+
+load_dotenv()
+
+
+get_weather_schema = {
+    "name": "get_weather",
+    "description": "Obtiene el estado del tiempo o clima actual para una ciudad o zona especificada.",
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "location": {
+                "type": "string",
+                "description": "Nombre de la ciudad o zona para consultar el clima.",
+            }
+        },
+        "required": ["location"],
+    },
+}
+
+
+def get_weather(location: str):
+    api_key = os.getenv("OPENWEATHER_API_KEY")
+    if not api_key:
+        return {"error": "Variable de entorno OPENWEATHER_API_KEY no configurada."}
+    try:
+        response = requests.get(
+            "https://api.openweathermap.org/data/2.5/weather",
+            params={"q": location, "appid": api_key, "units": "metric"},
+        )
+        data = response.json()
+        if response.status_code != 200:
+            return {
+                "error": data.get("message", "Error desconocido al obtener el clima.")
+            }
+        weather = {
+            "location": data["name"],
+            "description": data["weather"][0]["description"],
+            "temperature": data["main"]["temp"],
+            "humidity": data["main"]["humidity"],
+            "wind_speed": data["wind"]["speed"],
+        }
+        return {"weather": weather}
+    except Exception as e:
+        return {"error": f"Error al conectar con el servicio de clima: {e}"}
+
+
+get_weather_tool = Tool(get_weather_schema, get_weather)

agentify/llm/__init__.py

@@ -0,0 +1,6 @@
+from agentify.llm.client import LLMClientFactory, LLMClientType
+
+__all__ = [
+    "LLMClientFactory",
+    "LLMClientType",
+]

agentify/llm/client.py

@@ -0,0 +1,133 @@
+import os
+from dotenv import load_dotenv
+from typing import Union, Dict, Any, Optional, Callable
+from openai import OpenAI, AzureOpenAI
+
+load_dotenv()
+
+LLMClientType = Union[OpenAI, AzureOpenAI]
+
+ClientBuilder = Callable[[Dict[str, Any], int], LLMClientType]
+
+
+class LLMClientFactory:
+    """Factory class to create LLM client instances for different providers."""
+
+    SUPPORTED_PROVIDERS = ["azure", "openai", "deepseek", "gemini", "anthropic"]
+
+    def __init__(self, default_timeout: int = 30):
+        self.default_timeout = default_timeout
+        self._builders: Dict[str, ClientBuilder] = {
+            "openai": self._create_openai_client,
+            "deepseek": self._create_deepseek_client,
+            "gemini": self._create_gemini_client,
+            "azure": self._create_azure_client,
+            "anthropic": self._create_anthropic_client,
+            "llama": self._create_llama_client,
+        }
+
+    def _get_env_or_config(
+        self, key: str, env_var_name: str, config: Dict[str, Any], required: bool = True
+    ) -> Optional[str]:
+        """Helper to obtain a value from config_override or an environment variable."""
+        value = config.get(key, os.getenv(env_var_name))
+        if required and not value:
+            raise ValueError(
+                f"Parameter '{key}' (or environment variable '{env_var_name}') is required but was not found."
+            )
+        return value
+
+    def _create_openai_client(self, config: Dict[str, Any], timeout: int) -> OpenAI:
+        api_key = self._get_env_or_config("api_key", "OPENAI_API_KEY", config)
+        return OpenAI(
+            api_key=api_key,
+            timeout=timeout,
+        )
+
+    def _create_deepseek_client(self, config: Dict[str, Any], timeout: int) -> OpenAI:
+        api_key = self._get_env_or_config("api_key", "DEEPSEEK_API_KEY", config)
+        base_url = "https://api.deepseek.com"
+        return OpenAI(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    def _create_anthropic_client(self, config: Dict[str, Any], timeout: int) -> OpenAI:
+        api_key = self._get_env_or_config("api_key", "ANTHROPIC_API_KEY", config)
+        base_url = "https://api.anthropic.com/v1/"
+
+        return OpenAI(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    def _create_llama_client(self, config: Dict[str, Any], timeout: int) -> OpenAI:
+        api_key = self._get_env_or_config("api_key", "LLAMA_API_KEY", config)
+        base_url = "https://api.llama.com/compat/v1/"
+
+        return OpenAI(
+            api_key=api_key,
+            base_url=base_url,
+            timeout=timeout,
+        )
+
+    def _create_gemini_client(self, config: Dict[str, Any], timeout: int) -> OpenAI:
+        api_key = self._get_env_or_config("api_key", "GEMINI_API_KEY", config)
+        base_url = "https://generativelanguage.googleapis.com/v1beta/openai/"
+
+        client_args = {"api_key": api_key, "timeout": timeout}
+        if base_url:
+            client_args["base_url"] = base_url
+        else:
+            print(
+                "Warning: No GEMINI_URL provided for Gemini. Assuming the OpenAI SDK handles it or it's not needed."
+            )
+
+        return OpenAI(**client_args)
+
+    def _create_azure_client(self, config: Dict[str, Any], timeout: int) -> AzureOpenAI:
+        api_key = self._get_env_or_config("api_key", "AZURE_OPENAI_KEY", config)
+        api_version = self._get_env_or_config("api_version", "API_VERSION", config)
+        azure_endpoint = self._get_env_or_config(
+            "azure_endpoint", "AZURE_OPENAI_ENDPOINT", config
+        )
+        return AzureOpenAI(
+            api_key=api_key,
+            api_version=api_version,
+            azure_endpoint=azure_endpoint,
+            timeout=timeout,
+        )
+
+    def create_client(
+        self,
+        provider: str,
+        config_override: Optional[Dict[str, Any]] = None,
+        timeout: Optional[int] = None,
+    ) -> LLMClientType:
+        """Create an LLM client for the specified provider.
+
+        Args:
+            provider: Name of the provider (e.g., "openai", "azure").
+            config_override: Optional dict to override or provide configuration parameters (e.g., api_key, base_url) instead of using environment variables.
+            timeout: Specific timeout for this client; if not provided, the factory's default_timeout is used.
+
+        Returns:
+            An instance of the requested LLM client.
+
+        Raises:
+            ValueError: If the provider is not supported or required parameters are missing.
+        """
+        provider_lower = provider.lower()
+        if provider_lower not in self._builders:
+            raise ValueError(
+                f"Provider '{provider}' not supported. "
+                f"Supported: {', '.join(self.SUPPORTED_PROVIDERS)}"
+            )
+
+        builder_func = self._builders[provider_lower]
+        effective_timeout = timeout if timeout is not None else self.default_timeout
+        effective_config = config_override or {}
+
+        return builder_func(effective_config, effective_timeout)

agentify/memory/__init__.py

@@ -0,0 +1,17 @@
+from agentify.memory.interfaces import (
+    MemoryAddress,
+    Message,
+    ConversationStore,
+    TokenCounter,
+)
+from agentify.memory.service import MemoryService
+from agentify.memory.policies import MemoryPolicy
+
+__all__ = [
+    "MemoryAddress",
+    "Message",
+    "ConversationStore",
+    "TokenCounter",
+    "MemoryService",
+    "MemoryPolicy",
+]

agentify/memory/interfaces.py

@@ -0,0 +1,101 @@
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Protocol, Tuple
+from datetime import datetime, timezone
+import uuid
+
+
+@dataclass(frozen=True, slots=True)
+class MemoryAddress:
+    """
+    Composite key that identifies *where* messages live.
+    You control these fields from your API boundary.
+    Add/remove fields to match your domain (e.g., team_id, channel_id).
+    """
+    api_version: Optional[str] = None
+    tenant_id: Optional[str] = None
+    user_id: Optional[str] = None
+    conversation_id: Optional[str] = None
+    agent_id: Optional[str] = None
+    # extras lets you pass stable routing dimensions if needed.
+    extras: Tuple[Tuple[str, str], ...] = ()
+
+    def as_tuple(self) -> Tuple:
+        """Stable, hashable representation for keys and indexing."""
+        return (
+            self.api_version,
+            self.tenant_id,
+            self.user_id,
+            self.conversation_id,
+            self.agent_id,
+            self.extras,
+        )
+
+    def key_str(self, prefix: str = "mem") -> str:
+        """Human-readable key for key-value backends (e.g., Redis)."""
+        parts = [
+            ("v", self.api_version),
+            ("t", self.tenant_id),
+            ("u", self.user_id),
+            ("c", self.conversation_id),
+            ("a", self.agent_id),
+        ] + list(self.extras)
+        joined = ":".join(f"{k}={v}" for k, v in parts if v)
+        return f"{prefix}:{joined}" if joined else prefix
+
+
+@dataclass(slots=True)
+class Message:
+    """
+    Canonical chat message stored in the memory layer.
+    - content can be str or a list of parts (vision/multimodal).
+    - metadata is free-form and backend-agnostic.
+    """
+    role: str                                  # "system" | "user" | "assistant" | "tool"
+    content: Optional[Any] = None              # str | list[dict]
+    name: Optional[str] = None                 # tool name when role="tool"
+    tool_call_id: Optional[str] = None
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    ts: int = field(default_factory=lambda: int(datetime.now(timezone.utc).timestamp()))
+
+    def to_openai(self) -> Dict[str, Any]:
+        """Convert to OpenAI Chat Completions message format."""
+        d: Dict[str, Any] = {"role": self.role}
+        if self.content is not None:
+            d["content"] = self.content
+        if self.name is not None:
+            d["name"] = self.name
+        if self.tool_call_id is not None:
+            d["tool_call_id"] = self.tool_call_id
+        d.update(self.metadata)  # carry extra fields (e.g., tool_calls)
+        return d
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Backend-agnostic serialization (works with slots dataclasses)."""
+        return {
+            "role": self.role,
+            "content": self.content,
+            "name": self.name,
+            "tool_call_id": self.tool_call_id,
+            "metadata": self.metadata,
+            "id": self.id,
+            "ts": self.ts,
+        }
+
+class ConversationStore(Protocol):
+    """
+    Minimal CRUD for conversation histories.
+    The store does NOT generate addresses; it only consumes them.
+    """
+
+    def append_message(self, addr: MemoryAddress, msg: Message) -> None: ...
+    def read_messages(self, addr: MemoryAddress, start: int = 0, end: int = -1) -> List[Message]: ...
+    def replace_messages(self, addr: MemoryAddress, messages: List[Message]) -> None: ...
+    def delete_conversation(self, addr: MemoryAddress) -> None: ...
+    def set_ttl(self, addr: MemoryAddress, seconds: int) -> None: ...
+
+
+class TokenCounter(Protocol):
+    """Callable that returns token count for OpenAI-formatted messages."""
+    def __call__(self, openai_messages: List[Dict[str, Any]]) -> int: ...

agentify/memory/policies.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+from typing import Callable, List, Optional
+from .interfaces import ConversationStore, MemoryAddress, Message, TokenCounter
+
+
+class MemoryPolicy:
+    """
+    Role-based sliding window, optional token budget and summarization.
+    Backend-agnostic; operates via ConversationStore.
+    """
+
+    def __init__(
+        self,
+        store: ConversationStore,
+        *,
+        ttl_seconds: Optional[int] = None,
+        max_user_msgs: int = 6,
+        max_assistant_msgs: int = 6,
+        tokenizer: Optional[TokenCounter] = None,
+        max_tokens: Optional[int] = None,
+        summarizer: Optional[Callable[[List[Message]], Message]] = None,
+    ) -> None:
+        self.store = store
+        self.ttl = ttl_seconds
+        self.max_user = max_user_msgs
+        self.max_assistant = max_assistant_msgs
+        self.tokenizer = tokenizer
+        self.max_tokens = max_tokens
+        self.summarizer = summarizer
+
+    def _apply_ttl(self, addr: MemoryAddress) -> None:
+        if self.ttl:
+            self.store.set_ttl(addr, self.ttl)
+
+    def on_append(self, addr: MemoryAddress, msg: Message) -> None:
+        self.store.append_message(addr, msg)
+        self._apply_ttl(addr)
+        self._prune_window(addr)
+        self._ensure_token_budget(addr)
+
+    def _prune_window(self, addr: MemoryAddress) -> None:
+        msgs = self.store.read_messages(addr)
+        if not msgs:
+            return
+
+        system = msgs[0] if msgs[0].role == "system" else None
+        users = [i for i, m in enumerate(msgs) if m.role == "user"]
+        assistants = [i for i, m in enumerate(msgs) if m.role == "assistant"]
+
+        if len(users) <= self.max_user and len(assistants) <= self.max_assistant:
+            return
+
+        cutoff_user = users[-self.max_user] if len(users) > self.max_user else 0
+        cutoff_ass = assistants[-self.max_assistant] if len(assistants) > self.max_assistant else 0
+        cutoff = min(cutoff_user, cutoff_ass)
+        if cutoff <= 0:
+            return
+
+        new_msgs = msgs[cutoff:]
+        if system and (not new_msgs or new_msgs[0].role != "system"):
+            new_msgs.insert(0, system)
+
+        self.store.replace_messages(addr, new_msgs)
+
+    def _ensure_token_budget(self, addr: MemoryAddress) -> None:
+        if not (self.tokenizer and self.max_tokens):
+            return
+        msgs = self.store.read_messages(addr)
+        oai = [m.to_openai() for m in msgs]
+        if self.tokenizer(oai) <= self.max_tokens:
+            return
+        if self.summarizer:
+            system = msgs[0] if msgs and msgs[0].role == "system" else None
+            core = msgs[1:-6] if system else msgs[:-6]
+            tail = msgs[-6:]
+            if core:
+                summary = self.summarizer(core)
+                new_msgs = ([system] if system else []) + [summary] + tail
+                self.store.replace_messages(addr, new_msgs)