feather-ai-sdk 0.1.0__tar.gz

feather_ai_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: feather-ai-sdk
+Version: 0.1.0
+Summary: The lightest Agentic AI Framework you'll ever see
+Author: Luca Bozzetti
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-google-genai>=3.1.0
+Requires-Dist: langchain-openai>=1.0.3
+Requires-Dist: langchain-anthropic>=1.1.0
+Requires-Dist: langchain-mistralai>=1.0.1
+Requires-Dist: tavily-python>=00.7.13
+Requires-Dist: langchain-experimental>=0.4.0
+
+# Colors:
+
+BLUE VARIANTS:
+a) #0357c1
+b) #22c4e0
+
+PINK VARIANTS:
+a) #be3389
+
+ORANGE/BROWN VARIANTS:
+a) #dfa987

feather_ai_sdk-0.1.0/README.md

@@ -0,0 +1,11 @@
+# Colors:
+
+BLUE VARIANTS:
+a) #0357c1
+b) #22c4e0
+
+PINK VARIANTS:
+a) #be3389
+
+ORANGE/BROWN VARIANTS:
+a) #dfa987

feather_ai_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "feather-ai-sdk"
+version = "0.1.0"
+description = "The lightest Agentic AI Framework you'll ever see"
+authors = [{ name = "Luca Bozzetti" }]
+readme = "README.md"
+requires-python = ">=3.9,<3.14"
+dependencies = [
+    "langchain-google-genai>=3.1.0",
+    "langchain-openai>=1.0.3",
+    "langchain-anthropic>=1.1.0",
+    "langchain-mistralai>=1.0.1",
+    "tavily-python>=00.7.13",
+    "langchain-experimental>=0.4.0"
+]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"

feather_ai_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

feather_ai_sdk-0.1.0/src/feather_ai/__init__.py

@@ -0,0 +1,22 @@
+"""
+feather_ai
+==========
+
+Public API for the feather_ai package.
+"""
+
+from .agent import AIAgent
+from .document import Document
+from .prompt import Prompt
+from .utils import load_instruction_from_file
+from src.feather_ai.internal_utils._exceptions import ModelNotSupportedException
+from src.feather_ai.internal_utils._response import AIResponse
+
+__all__ = [
+    "AIAgent",
+    "Document",
+    "Prompt",
+    "load_instruction_from_file",
+    "ModelNotSupportedException",
+    "AIResponse",
+]

feather_ai_sdk-0.1.0/src/feather_ai/agent.py

@@ -0,0 +1,115 @@
+"""
+This file contains the main Agent class provided by feather_ai.
+The AIAgent class can be used to create intelligent agents that can perform various tasks.
+Its main advantage over other agentic AI frameworks is its simplicity and ease of use.
+"""
+from typing import Optional, List, Callable, Any, Dict, Type
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import HumanMessage, SystemMessage, BaseMessage, AIMessage
+from langchain_core.runnables import Runnable
+from pydantic import BaseModel
+
+from src.feather_ai.internal_utils._provider import get_provider
+from src.feather_ai.internal_utils._response import AIResponse
+from .internal_utils._structured_tool import get_respond_tool
+from .prompt import Prompt
+from .internal_utils._tools import make_tool, execute_tool, async_execute_tool, react_agent_with_tooling, \
+    async_react_agent_with_tooling
+from .internal_utils._tracing import get_tool_trace_from_langchain
+
+
+class AIAgent:
+    """
+    The AIAgent class represents an intelligent AI agent that can perform tool calling and give structured output.
+    
+    Attributes:
+        model (str): The LLM used by the agent.
+    """
+
+    def __init__(self,
+                 model: str,
+                 instructions: Optional[str] = None,
+                 tools: Optional[List[Callable[..., Any]]] = None,
+                 output_schema: Optional[Type[BaseModel]] = None,
+                 ):
+        """
+        Initializes a new Agent instance.
+
+        Args:
+            model (str): The LLM used by the agent.
+        """
+        self.model = model
+        self.system_instructions = instructions
+        self.structured_output = True if output_schema else False
+        provider_data = get_provider(model)
+        self.llm: BaseChatModel | Runnable = provider_data[0]
+        if self.structured_output and not tools:
+            self.llm = self.llm.with_structured_output(output_schema)
+        self.provider_str: str = provider_data[1]
+        # Bind tools to LLM
+        if tools:
+            self.tools = [make_tool(tool) for tool in tools]
+            if self.structured_output:
+                self.tools.append(get_respond_tool(output_schema))
+                self.llm: BaseChatModel = get_provider(model)[0].bind_tools(self.tools, tool_choice='any')  # type: ignore
+            else:
+                self.llm: BaseChatModel = get_provider(model)[0].bind_tools(self.tools) # type: ignore
+
+    def run(self, prompt: Prompt | str):
+        """
+        Standard run method for the AIAgent class.
+        Returns:
+            AgentResponse object containing the agent's response.
+        """
+        messages: List[BaseMessage] = [
+            SystemMessage(content=self.system_instructions if self.system_instructions else ""),
+        ]
+
+        ## Check if user passed a Prompt Object or a string
+        if isinstance(prompt, Prompt):
+            messages.append(prompt.get_message(self.provider_str))
+        else:
+            messages.append(HumanMessage(content=prompt))
+
+        tool_calls = None
+        ## Call tools if any
+        if hasattr(self, "tools"):
+            response, tool_calls = react_agent_with_tooling(self.llm, self.tools, messages, self.structured_output)
+        else:
+            response = self.llm.invoke(messages)
+
+        ## Check for structured output
+        if self.structured_output:
+            return AIResponse(response, tool_calls, messages)
+        else:
+            return AIResponse(response.content, tool_calls, messages)
+
+    async def arun(self, prompt: Prompt | str):
+        """
+        Async run method for the AIAgent class.
+        Returns:
+            AgentResponse object containing the agent's response.
+        """
+        messages: List[BaseMessage] = [
+            SystemMessage(content=self.system_instructions if self.system_instructions else ""),
+        ]
+
+        ## Check if user passed a Prompt Object or a string
+        if isinstance(prompt, Prompt):
+            messages.append(prompt.get_message(self.provider_str))
+        else:
+            messages.append(HumanMessage(content=prompt))
+
+        tool_calls = None
+        ## Call tools if any
+        if hasattr(self, "tools"):
+            response, tool_calls = await async_react_agent_with_tooling(self.llm, self.tools, messages, self.structured_output)
+        else:
+            response = await self.llm.ainvoke(messages)
+
+        ## Check for structured output
+        if self.structured_output:
+            return AIResponse(response, tool_calls, messages)
+        else:
+            return AIResponse(response.content, tool_calls, messages)

feather_ai_sdk-0.1.0/src/feather_ai/document.py

@@ -0,0 +1,35 @@
+"""
+Provides a standardized Document class for multimodal prompts.
+Can either be called by the user or automatically from the Prompt class.
+"""
+from dataclasses import dataclass
+from io import BytesIO
+import mimetypes
+from pathlib import Path
+
+
+@dataclass
+class Document:
+    """Represents a document with content and metadata."""
+    content: bytes
+    mime_type: str
+    filename: str = ""
+
+    @classmethod
+    def from_path(cls, path: str | Path) -> "Document":
+        """Create document from file path."""
+        path = Path(path)
+        content = path.read_bytes()
+        mime_type = mimetypes.guess_type(path)[0] or "application/octet-stream"
+        return cls(content=content, mime_type=mime_type, filename=path.name)
+
+    @classmethod
+    def from_bytes(cls, content: bytes, mime_type: str, filename: str | None = None) -> "Document":
+        """Create document from bytes."""
+        return cls(content=content, mime_type=mime_type, filename=filename)
+
+    @classmethod
+    def from_bytesio(cls, buffer: BytesIO, mime_type: str, filename: str | None = None) -> "Document":
+        """Create document from BytesIO."""
+        content = buffer.getvalue()
+        return cls(content=content, mime_type=mime_type, filename=filename)

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_exceptions.py

@@ -0,0 +1,29 @@
+"""
+Custom exceptions for feather_ai.
+"""
+from typing import Optional
+
+
+class ModelNotSupportedException(Exception):
+    """
+    Raised when a user requests a model that the library does not support.
+
+    Attributes:
+        model_name (str): The name of the unsupported model.
+    """
+
+    def __init__(self, model_name: str, message: str | None = None):
+        if message is None:
+            message = f"Model '{model_name}' is not supported by feather_ai."
+        super().__init__(message)
+        self.model_name = model_name
+
+class ApiKeyMissingException(Exception):
+    """
+    Raised when an API key for the requested provider is missing.
+    """
+
+    def __init__(self, provider: Optional[str] = None, env_key: Optional[str] = None, message: str | None = None):
+        if message is None:
+            message = f"API key for provider '{provider}' is missing. Please set the environment variable '{env_key}'."
+        super().__init__(message)

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_multimodal.py

@@ -0,0 +1,62 @@
+"""
+All providers handle multimodality differently so this defines all the message types
+"""
+import base64
+from typing import Dict, Any, List
+
+from src.feather_ai.document import Document
+
+
+def get_content_claude(documents: List[Document]) -> List[Dict[str, Any]]:
+    """
+    helper to build multimodal content for Claude
+    """
+    content_claude = []
+    for doc in documents:
+        if doc.mime_type == "application/pdf":
+            # PDFs use the document type
+            content_claude.append({
+                "type": "document",
+                "source": {
+                    "type": "base64",
+                    "media_type": "application/pdf",
+                    "data": base64.b64encode(doc.content).decode("utf-8")
+                }
+            })
+        elif doc.mime_type.startswith("image/"):
+            # Images use the image type
+            content_claude.append({
+                "type": "image",
+                "source": {
+                    "type": "base64",
+                    "media_type": doc.mime_type,
+                    "data": base64.b64encode(doc.content).decode("utf-8")
+                }
+            })
+        elif doc.mime_type.startswith("text/") or doc.mime_type in ["application/json", "application/xml"]:
+            # Text files: decode and include as text
+            try:
+                text_content_decoded = doc.content.decode("utf-8")
+                content_claude.append({
+                    "type": "text",
+                    "text": f"\n--- Content of {doc.filename or 'file'} ---\n{text_content_decoded}\n--- End of {doc.filename or 'file'} ---\n"
+                })
+            except UnicodeDecodeError:
+                pass
+        else:
+            # Unsupported format for Claude
+            raise ValueError(f"Unsupported file type for Claude: {doc.mime_type}")
+
+    return content_claude
+
+def get_content_gemini(documents: List[Document]) -> List[Dict[str, Any]]:
+    """
+        helper to build multimodal content for Gemini
+    """
+    content_gemini = [{
+        "type": "media",
+        "mime_type": doc.mime_type,
+        "data": base64.b64encode(doc.content).decode("utf-8")
+    } for doc in documents]
+
+    return content_gemini

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_provider.py

@@ -0,0 +1,57 @@
+import os
+from typing import Tuple
+
+from langchain_google_genai import ChatGoogleGenerativeAI
+from langchain_mistralai import ChatMistralAI
+from langchain_openai import ChatOpenAI
+from langchain_anthropic import ChatAnthropic
+from langchain_core.language_models.chat_models import BaseChatModel
+from ._exceptions import ModelNotSupportedException, ApiKeyMissingException
+
+provider_mapping = {
+    "gemini": ChatGoogleGenerativeAI,
+    "claude": ChatAnthropic,
+    "openai": ChatOpenAI,
+    "mistral": ChatMistralAI
+}
+
+model_mapping = {
+    "gemini": lambda model: model.startswith("gemini"),
+    "claude": lambda model: model.startswith("claude"),
+    "openai": lambda model: model.startswith("gpt"),
+    "mistral": lambda model: model.startswith("mistral")
+}
+
+env_vars = {
+    "gemini": "GOOGLE_API_KEY",
+    "claude": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "mistral": "MISTRAL_API_KEY"
+}
+
+def get_provider(model: str) -> Tuple[BaseChatModel, str]:
+    """
+    get the specified LLM provider baseclass
+    Args:
+        model: string containing model name
+
+    Returns:
+    The Chat baseclass from langchain
+    """
+    provider_key = None
+    # Extract the provider prefix from the model name
+    for key in provider_mapping.keys():
+        if model_mapping[key](model):
+            provider_key = key
+            break
+
+    # Error handling if model does not exist
+    if provider_key is None:
+        raise ModelNotSupportedException(model)
+
+    if not os.getenv(env_vars[provider_key]):
+        raise ApiKeyMissingException(provider_key, env_vars[provider_key])
+
+    return provider_mapping[provider_key](
+        model=model  # type: ignore
+    ), provider_key

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_response.py

@@ -0,0 +1,21 @@
+"""
+Contains the Response class that summarizes a response from an AI Agent
+"""
+from typing import Optional, List, Type
+
+from langchain_core.messages import BaseMessage
+from pydantic import BaseModel
+from src.feather_ai.internal_utils._tracing import ToolTrace
+
+
+class AIResponse:
+    def __init__(self, content: str | BaseModel, tool_calls: Optional[List[ToolTrace]] = None, input_messages: Optional[List[BaseMessage]] = None):
+        self.content = content
+        self.tool_calls = tool_calls
+        self.input_messages = input_messages
+
+    def __str__(self):
+        if self.tool_calls:
+            return f"AIResponse(content={self.content}, tool_calls={[str(tool_call) for tool_call in self.tool_calls]})"
+        else:
+            return f"AIResponse(content={self.content})"

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_structured_tool.py

@@ -0,0 +1,62 @@
+"""
+This is a bit of a hacky way to combine tool calling with structured output.
+Inspired by https://langchain-ai.github.io/langgraph/how-tos/react-agent-structured-output/#define-graph
+We use a respond() tool to return structured output.
+"""
+
+from typing import Type
+from pydantic import BaseModel
+from langchain_core.tools import StructuredTool
+
+
+def get_respond_tool(schema: Type[BaseModel]) -> StructuredTool:
+    """
+    Generates a LangChain tool named 'respond' based on a Pydantic schema.
+    """
+
+    # 1. Define the function logic
+    # We accept **kwargs so the function can accept any arguments defined in the schema.
+    # We simply instantiate the Pydantic model with these arguments.
+    def respond_func(**kwargs) -> BaseModel:
+        return schema(**kwargs)
+
+    # 2. Construct the dynamic docstring
+    # Start with the fixed header required by the prompt
+    docstring_parts = [
+        "This is the tool you should use to respond to the user when you do not want to make any other tool calls. "
+        "The user requested for structured output which will be provided through this tool."
+        "Please always use this tool ALONE and only call it ONCE, without calling any other tools.",
+        "",
+        "Args:"
+    ]
+
+    # Iterate over the Pydantic model fields to generate the Args section
+    # Note: Uses Pydantic v2 'model_fields'. For v1, use '__fields__'.
+    field_names = []
+    for name, field in schema.model_fields.items():
+        field_names.append(name)
+        description = field.description
+
+        # If a description exists, append it; otherwise just list the name
+        if description:
+            docstring_parts.append(f"{name}: {description}")
+        else:
+            docstring_parts.append(f"{name}:")
+
+    # Add the Returns section
+    docstring_parts.append("")
+    docstring_parts.append("Returns:")
+    docstring_parts.append(f"A {schema.__name__} object with the fields {', '.join(field_names)}")
+
+    # Join the parts to create the final docstring
+    respond_func.__doc__ = "\n".join(docstring_parts)
+
+    # 3. Create and return the StructuredTool
+    # We pass the original schema as 'args_schema'. LangChain uses this to
+    # generate the JSON Schema for the LLM (handling types, defaults, and optionals automatically).
+    return StructuredTool.from_function(
+        func=respond_func,
+        name="respond",
+        description=respond_func.__doc__,
+        args_schema=schema
+    )

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_tools.py

@@ -0,0 +1,227 @@
+"""
+Helper functions for tool calling
+"""
+import asyncio
+from typing import Callable, Any, get_type_hints, List, Tuple, Type
+
+from langchain_core.language_models import BaseChatModel
+from langchain_core.messages import ToolMessage, BaseMessage, AIMessage
+from langchain_core.tools import StructuredTool, BaseTool
+from pydantic import create_model, BaseModel
+import inspect
+import logging
+logger = logging.getLogger(__name__)
+
+from src.feather_ai.internal_utils._tracing import ToolTrace, get_tool_trace_from_langchain
+
+def execute_tool(response, tools):
+    """
+    Helper function to execute tool calls in the response from the LLM.
+    """
+    messages = []
+    # Following code was copied from the tutorial about MCP:
+    # Check if the LLM made tool calls
+    if hasattr(response, 'tool_calls') and response.tool_calls:
+        logger.info(f"Calling the following tools: {response.tool_calls}")
+        # Add the assistant message with tool calls to our conversation
+        messages.append(response)
+
+        # Execute each tool call and create proper tool messages
+        for tool_call in response.tool_calls:
+            tool_name = tool_call['name']
+            tool_args = tool_call['args']
+            tool_call_id = tool_call['id']
+
+            # Find and execute the tool
+            tool_result = None
+            for tool in tools:
+                if hasattr(tool, 'coroutine') and tool.coroutine is not None:
+                    raise ValueError("You cannot use the normal run method with asynchronous tools. Use the arun method instead.")
+                if tool.name == tool_name:
+                    try:
+                        tool_result = tool.run(tool_args)
+                    except Exception as tool_error:
+                        tool_result = f"Error executing tool: {tool_error}"
+                    break
+
+            if tool_result is None:
+                tool_result = f"Tool {tool_name} not found"
+
+            # Create a tool message
+            tool_message = ToolMessage(
+                content=str(tool_result),
+                tool_call_id=tool_call_id
+            )
+            messages.append(tool_message)
+
+    return messages
+
+
+async def async_execute_tool(response, tools):
+    """
+    Helper function to execute tool calls in the response from the LLM.
+    Calls all tools asynchronously in parallel.
+    """
+    messages = []
+
+    # Check if the LLM made tool calls
+    if hasattr(response, 'tool_calls') and response.tool_calls:
+        logger.info(f"Calling the following tools: {response.tool_calls}")
+        # Add the assistant message with tool calls to our conversation
+        messages.append(response)
+
+        # Create async tasks for all tool calls
+        async def execute_single_tool(tool_call):
+            tool_name = tool_call['name']
+            tool_args = tool_call['args']
+            tool_call_id = tool_call['id']
+
+            # Find and execute the tool
+            tool_result = None
+            for tool in tools:
+                if tool.name == tool_name:
+                    try:
+                        # Check if tool has a coroutine (async) or func (sync)
+                        if hasattr(tool, 'coroutine') and tool.coroutine is not None:
+                            tool_result = await tool.arun(tool_args)
+                        else:
+                            logger.warning("Using synchronous tools will lead to sequential tool execution. Consider using asynchronous tools instead.")
+                            tool_result = tool.run(tool_args)
+                    except Exception as tool_error:
+                        tool_result = f"Error executing tool: {tool_error}"
+                    break
+
+            if tool_result is None:
+                tool_result = f"Tool {tool_name} not found"
+
+            # Create and return a tool message
+            return ToolMessage(
+                content=str(tool_result),
+                tool_call_id=tool_call_id
+            )
+
+        # Execute all tools in parallel
+        tool_messages = await asyncio.gather(
+            *[execute_single_tool(tc) for tc in response.tool_calls]
+        )
+
+        messages.extend(tool_messages)
+
+    return messages
+
+async def async_react_agent_with_tooling(llm: BaseChatModel, tools: List[BaseTool], messages: List[BaseMessage], structured_output: bool = False) -> Tuple[AIMessage | Type[BaseModel], List[ToolTrace]]:
+    """
+    Agent that can call tools in multiple rounds.
+    Args:
+        llm: langchain chat model
+        tools: tools to be called by the chat model
+        messages: current conversation
+        structured_output: optional flag to indicate if the agent should return structured output
+
+    Returns:
+
+    """
+    tool_calls = []
+    while True:
+        response = await llm.ainvoke(messages)
+
+        # sorry for this hack, would not be necessary if langchain supported tool calls with structured output
+        if structured_output and hasattr(response, 'tool_calls') and response.tool_calls:
+            for tool_call in response.tool_calls:
+                if tool_call['name'] == 'respond':
+                    tool_args = tool_call['args']
+                    for tool in tools:
+                        if tool.name == 'respond':
+                            return tool.run(tool_args), tool_calls
+
+        tool_messages = await async_execute_tool(response, tools)
+        tool_calls.extend(get_tool_trace_from_langchain(response, tool_messages))
+        if not tool_messages:
+            if response.content:
+                return response, tool_calls
+            else:
+                response.content = messages[-1].content
+                return response, tool_calls
+        messages.extend(tool_messages)
+
+def react_agent_with_tooling(llm: BaseChatModel, tools: List[BaseTool], messages: List[BaseMessage], structured_output: bool = False) -> Tuple[AIMessage | Type[BaseModel], List[ToolTrace]]:
+    """
+    Agent that can call tools in multiple rounds.
+    Args:
+        llm: langchain chat model
+        tools: tools to be called by the chat model
+        messages: current conversation
+        structured_output: optional flag to indicate if the agent should return structured output
+
+    Returns:
+
+    """
+    tool_calls = []
+    while True:
+        response = llm.invoke(messages)
+
+        # sorry for this hack, would not be necessary if langchain supported tool calls with structured output
+        if structured_output and hasattr(response, 'tool_calls') and response.tool_calls:
+            for tool_call in response.tool_calls:
+                if tool_call['name'] == 'respond':
+                    tool_args = tool_call['args']
+                    for tool in tools:
+                        if tool.name == 'respond':
+                            return tool.run(tool_args), tool_calls
+
+        tool_messages = execute_tool(response, tools)
+        tool_calls.extend(get_tool_trace_from_langchain(response, tool_messages))
+        if not tool_messages:
+            if response.content:
+                return response, tool_calls
+            else:
+                response.content = messages[-1].content
+                return response, tool_calls
+        messages.extend(tool_messages)
+
+
+def make_tool(func: Callable) -> StructuredTool:
+    """
+    Convert any function into a LangChain StructuredTool.
+
+    Args:
+        func: Any callable function with type hints
+
+    Returns:
+        A LangChain StructuredTool wrapping the function
+    """
+    if isinstance(func, BaseTool):
+        return func
+    # Get function metadata
+    tool_name = func.__name__
+    tool_description = func.__doc__ or f"Run {func.__name__}"
+
+    # Get function signature and type hints
+    sig = inspect.signature(func)
+    type_hints = get_type_hints(func)
+
+    # Build Pydantic model fields from parameters
+    fields = {}
+    for param_name, param in sig.parameters.items():
+        param_type = type_hints.get(param_name, Any)
+        param_default = ... if param.default == inspect.Parameter.empty else param.default
+        fields[param_name] = (param_type, param_default)
+
+    # Create Pydantic model for schema
+    InputSchema = create_model(f"{tool_name}Input", **fields)
+
+    # Use 'coroutine' parameter for async functions, 'func' for sync functions
+    if asyncio.iscoroutinefunction(func):
+        return StructuredTool(
+            name=tool_name,
+            description=tool_description,
+            args_schema=InputSchema,
+            coroutine=func
+        )
+    else:
+        return StructuredTool(
+            name=tool_name,
+            description=tool_description,
+            args_schema=InputSchema,
+            func=func
+        )

feather_ai_sdk-0.1.0/src/feather_ai/internal_utils/_tracing.py

@@ -0,0 +1,36 @@
+"""
+Everything related to tracing LLM calls
+"""
+from dataclasses import dataclass
+from langchain_core.messages import AIMessage, ToolMessage, BaseMessage
+
+
+def get_tool_trace_from_langchain(response: AIMessage, messages: list[BaseMessage]):
+    tool_traces = []
+    tool_calls = response.tool_calls
+    tool_messages = [message for message in messages if isinstance(message, ToolMessage)]
+
+    # error handling:
+    if len(tool_calls) != len(tool_messages):
+        raise ValueError("Number of tool calls and tool responses do not match."
+                         f"len tool calls: {len(tool_calls)}, len responses: {len(tool_messages)}."
+                         f"response: {response}, tool_messages: {tool_messages}")
+
+    for idx, tool_call in enumerate(tool_calls):
+        tool_name = tool_call['name']
+        tool_args = tool_call['args']
+
+        tool_input = f"{tool_name}({tool_args})"
+        output = tool_messages[idx].content
+        tool_traces.append(ToolTrace(tool_name, tool_input, output))
+
+    return tool_traces
+
+@dataclass
+class ToolTrace:
+    tool_name: str
+    input: str
+    output: str
+
+    def __str__(self) -> str:
+        return f"{self.input}: {self.output}"

feather_ai_sdk-0.1.0/src/feather_ai/prompt.py

@@ -0,0 +1,59 @@
+from pathlib import Path
+from typing import Union
+from langchain_core.messages import HumanMessage
+from src.feather_ai.internal_utils._multimodal import get_content_claude, get_content_gemini
+from src.feather_ai.document import Document
+
+
+class Prompt:
+    """
+    The prompt class can be used to create a multimodal prompt with documents, images, etc.
+    """
+    def __init__(
+        self, 
+        text: str, 
+        documents: list[Union[str, Path, Document]] = None
+    ):
+        self.text = text
+        self.documents: list[Document] = []
+        
+        if documents:
+            for doc in documents:
+                if isinstance(doc, (str, Path)):
+                    self.documents.append(Document.from_path(doc))
+                elif isinstance(doc, Document):
+                    self.documents.append(doc)
+                else:
+                    raise TypeError(f"Unsupported document type: {type(doc)}")
+
+            # create the messages (different for each provider)
+            text_content = [
+                {"type": "text", "text": text},
+                {"type": "text", "text": "The user uploaded the following documents:"},
+                {"type": "text", "text": f"[{[doc.filename for doc in self.documents]}]"}
+            ]
+
+            self.message_map = {
+                "gemini": HumanMessage(
+                    content=text_content + get_content_gemini(self.documents)
+                ),
+                "claude": HumanMessage(
+                    content=text_content + get_content_claude(self.documents)
+                )
+            }
+        else:
+            self.message = HumanMessage(content=text)
+
+    def get_message(self, provider: str) -> HumanMessage:
+        if provider in ["mistral", "openai"] and hasattr(self, "message_map"):
+            raise ValueError(
+                f"Provider {provider} does not support multimodal prompts yet."
+                f"Please process your PDF into text first and then give a simple text Prompt."
+            )
+        if self.documents:
+            try:
+                return self.message_map[provider]
+            except KeyError:
+                raise ValueError(f"Provider {provider} is not supported.")
+
+        return self.message

feather_ai_sdk-0.1.0/src/feather_ai/tools/__init__.py

@@ -0,0 +1,53 @@
+"""
+feather_ai.tools
+================
+
+Public API for the feather_ai tools package.
+Provides ready-to-use tools for AI agents.
+"""
+
+from .web import (
+    google_search,
+    google_search_async,
+    extract,
+    extract_async,
+    crawl,
+    crawl_async,
+    web_tools,
+    web_tools_async,
+)
+from .code_execution import code_execution_python
+
+# Sync tools list
+all_tools = [
+    google_search,
+    extract,
+    crawl,
+    code_execution_python,
+]
+
+# Async tools list
+all_tools_async = [
+    google_search_async,
+    extract_async,
+    crawl_async,
+]
+
+__all__ = [
+    # Web tools (sync)
+    "google_search",
+    "extract",
+    "crawl",
+    # Web tools (async)
+    "google_search_async",
+    "extract_async",
+    "crawl_async",
+    # Web tool lists
+    "web_tools",
+    "web_tools_async",
+    # Code execution
+    "code_execution_python",
+    # All tools lists
+    "all_tools",
+    "all_tools_async",
+]

feather_ai_sdk-0.1.0/src/feather_ai/tools/code_execution.py

@@ -0,0 +1,19 @@
+"""
+Defines tools for native code execution.
+"""
+
+from langchain_experimental.utilities import PythonREPL
+
+_python_repl = None
+
+def code_execution_python(python_code: str) -> str:
+    """
+    A Python shell. Use this to execute python commands. Input should be a valid python command. If you want to see the output of a value, you should print it out with `print(...)`.
+    Returns:
+        Python output as a string
+    """
+    global _python_repl
+    if not _python_repl:
+        _python_repl = PythonREPL()
+
+    return _python_repl.run(python_code)

feather_ai_sdk-0.1.0/src/feather_ai/tools/web.py

@@ -0,0 +1,174 @@
+import json
+import os
+from typing import Optional, List, Dict
+from tavily import TavilyClient, AsyncTavilyClient
+
+from src.feather_ai.internal_utils._exceptions import ApiKeyMissingException
+
+_client: Optional[TavilyClient] = None
+_async_client: Optional[TavilyClient] = None
+
+def google_search(query: str) -> str:
+    """
+    Simple google search tool for recent events and facts
+    Args:
+        query: Your search query
+
+    Returns:
+        A curated list of relevant results
+    """
+    global _client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(message="I you want to use the google search tool, please set the environment variable TAVILY_API_KEY."
+                                             "You can get a free API key at https://www.tavily.com/")
+    if not _client:
+        _client = TavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    search_response = _client.search(query)
+
+    # Curate the results into a markdown string
+    def curate_results(result: dict):
+        """Turn the search results into a markdown string for better readability"""
+        return (f"Title: {result.get("title", "")}\nurl: {result.get("url", "")}\n"
+                f"Content Snippets: {result.get("content", "")}")
+
+    curated_results = [curate_results(result) for result in search_response["results"]]
+    return "\n\n".join(curated_results)
+
+async def google_search_async(query: str) -> str:
+    """
+        Simple google search tool for recent events and facts
+        Performs a google search with the given query and returns a list of relevant search results
+        Args:
+            query: Your search query
+
+        Returns:
+            A curated list of relevant results
+        """
+    global _async_client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(
+            message="I you want to use the google search tool, please set the environment variable TAVILY_API_KEY."
+                    "You can get a free API key at https://www.tavily.com/")
+    if not _async_client:
+        _async_client = AsyncTavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    search_response = await _async_client.search(query)
+
+    # Curate the results into a markdown string
+    def curate_results(result: Dict[str, str]):
+        """Turn the search results into a markdown string for better readability"""
+        return (f"Title: {result.get("title", "")}\nurl: {result.get("url", "")}\n"
+                f"Content Snippets: {result.get("content", "")}")
+
+    curated_results = [curate_results(result) for result in search_response["results"]]
+    return "\n\n".join(curated_results)
+
+def extract(urls: List[str]) -> List[Dict]:
+    """
+    Extracts raw content from the provided urls
+    Args:
+        urls: list of urls that should be extracted
+
+    Returns:
+        Dict with keys url, raw_content and favicon
+    """
+    global _client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(
+            message="I you want to use web tools like extract, please set the environment variable TAVILY_API_KEY."
+                    "You can get a free API key at https://www.tavily.com/")
+    if not _client:
+        _client = TavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    response = _client.extract(urls)
+
+    from pprint import pprint
+    pprint(response)
+
+    # filter response to only include relevant keys
+    keys = ["title", "url", "raw_content", "favicon"]
+    errors = response.get("failed_results", [""])
+    filtered_dicts = [{k: result.get(k) for k in keys if k in result} for result in response["results"]]
+
+    return errors + filtered_dicts
+
+
+async def extract_async(urls: List[str]) -> List[Dict]:
+    """
+    Extracts raw content from the provided urls
+    Args:
+        urls: list of urls that should be extracted
+
+    Returns:
+        Dict with keys url, raw_content and favicon
+    """
+    global _async_client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(
+            message="I you want to use web tools like extract, please set the environment variable TAVILY_API_KEY."
+                    "You can get a free API key at https://www.tavily.com/")
+    if not _async_client:
+        _async_client = AsyncTavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    response = await _async_client.extract(urls)
+
+    # filter response to only include relevant keys
+    keys = ["title", "url", "raw_content", "favicon"]
+    errors = response.get("failed_results", [""])
+    filtered_dicts = [{k: result.get(k) for k in keys if k in result} for result in response["results"]]
+
+    return errors + filtered_dicts
+
+def crawl(base_url: str) -> List[str]:
+    """
+    Extracts all subpages of the given url
+    Args:
+        base_url: the base url to start the crawl from
+
+    Returns:
+        a list of suppages that can be extracted with the extract tool
+    """
+    global _client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(message="I you want to use the google search tool, please set the environment variable TAVILY_API_KEY."
+                                             "You can get a free API key at https://www.tavily.com/")
+    if not _client:
+        _client = TavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    response = _client.map(base_url)
+
+    return response["results"]
+
+
+async def crawl_async(base_url: str) -> List[str]:
+    """
+    Extracts all subpages of the given url
+    Args:
+        base_url: the base url to start the crawl from
+
+    Returns:
+        a list of suppages that can be extracted with the extract tool
+    """
+    global _async_client
+    if not os.getenv("TAVILY_API_KEY"):
+        raise ApiKeyMissingException(message="I you want to use the google search tool, please set the environment variable TAVILY_API_KEY."
+                                             "You can get a free API key at https://www.tavily.com/")
+    if not _async_client:
+        _async_client = AsyncTavilyClient(os.getenv("TAVILY_API_KEY"))
+
+    response = await _async_client.map(base_url)
+
+    return response["results"]
+
+web_tools = [google_search, extract, crawl]
+web_tools_async = [google_search_async, extract_async, crawl_async]
+
+
+
+if __name__ == "__main__":
+    from dotenv import load_dotenv
+    from pprint import pprint
+    load_dotenv()
+    result = google_search("Champions League Winner 2025")
+    print(result)

feather_ai_sdk-0.1.0/src/feather_ai/utils.py

@@ -0,0 +1,24 @@
+"""
+This class exposes some utility functions commonly used for AI agents
+"""
+import os
+import logging
+logger = logging.getLogger(__name__)
+
+
+def load_instruction_from_file(
+    filename: str, default_instruction: str = "Default instruction."
+) -> str:
+    """Reads instruction text from a single file relative to the caller's working directory."""
+    instruction = default_instruction
+    try:
+        # Use current working directory instead of script location
+        filepath = os.path.join(os.getcwd(), filename)
+        with open(filepath, "r", encoding="utf-8") as f:
+            instruction = f.read()
+            logger.info("Successfully loaded instruction from %s", filename)
+    except FileNotFoundError:
+        logger.warning("Instruction file not found: %s. Using default.", filepath)
+    except Exception as e:
+        logger.exception("ERROR loading instruction file %s: %s. Using default.", filepath, e)
+    return instruction

feather_ai_sdk-0.1.0/src/feather_ai_sdk.egg-info/PKG-INFO

@@ -0,0 +1,25 @@
+Metadata-Version: 2.4
+Name: feather-ai-sdk
+Version: 0.1.0
+Summary: The lightest Agentic AI Framework you'll ever see
+Author: Luca Bozzetti
+Requires-Python: <3.14,>=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: langchain-google-genai>=3.1.0
+Requires-Dist: langchain-openai>=1.0.3
+Requires-Dist: langchain-anthropic>=1.1.0
+Requires-Dist: langchain-mistralai>=1.0.1
+Requires-Dist: tavily-python>=00.7.13
+Requires-Dist: langchain-experimental>=0.4.0
+
+# Colors:
+
+BLUE VARIANTS:
+a) #0357c1
+b) #22c4e0
+
+PINK VARIANTS:
+a) #be3389
+
+ORANGE/BROWN VARIANTS:
+a) #dfa987

feather_ai_sdk-0.1.0/src/feather_ai_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,26 @@
+README.md
+pyproject.toml
+src/__init__.py
+src/feather_ai/__init__.py
+src/feather_ai/agent.py
+src/feather_ai/document.py
+src/feather_ai/prompt.py
+src/feather_ai/utils.py
+src/feather_ai/internal_utils/__init__.py
+src/feather_ai/internal_utils/_exceptions.py
+src/feather_ai/internal_utils/_multimodal.py
+src/feather_ai/internal_utils/_provider.py
+src/feather_ai/internal_utils/_response.py
+src/feather_ai/internal_utils/_structured_tool.py
+src/feather_ai/internal_utils/_tools.py
+src/feather_ai/internal_utils/_tracing.py
+src/feather_ai/orchestration/__init__.py
+src/feather_ai/tools/__init__.py
+src/feather_ai/tools/code_execution.py
+src/feather_ai/tools/web.py
+src/feather_ai_sdk.egg-info/PKG-INFO
+src/feather_ai_sdk.egg-info/SOURCES.txt
+src/feather_ai_sdk.egg-info/dependency_links.txt
+src/feather_ai_sdk.egg-info/requires.txt
+src/feather_ai_sdk.egg-info/top_level.txt
+tests/test_agent.py

feather_ai_sdk-0.1.0/src/feather_ai_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

feather_ai_sdk-0.1.0/src/feather_ai_sdk.egg-info/requires.txt

@@ -0,0 +1,6 @@
+langchain-google-genai>=3.1.0
+langchain-openai>=1.0.3
+langchain-anthropic>=1.1.0
+langchain-mistralai>=1.0.1
+tavily-python>=00.7.13
+langchain-experimental>=0.4.0

feather_ai_sdk-0.1.0/src/feather_ai_sdk.egg-info/top_level.txt

@@ -0,0 +1,2 @@
+__init__
+feather_ai

feather_ai_sdk-0.1.0/tests/test_agent.py

@@ -0,0 +1,146 @@
+"""
+Testing the AIAgent baseclass
+Models:
+claude-haiku-4-5
+gpt-5-nano
+gemini-2.5-flash-lite
+mistral-small-2506
+"""
+import asyncio
+import os
+from pprint import pprint
+
+from dotenv import load_dotenv
+from pydantic import BaseModel, Field
+import logging
+
+from src.feather_ai.tools.code_execution import code_execution_python
+from src.feather_ai.tools.web import google_search, web_tools, web_tools_async
+
+logging.basicConfig(level=logging.INFO)
+
+from src.feather_ai import AIAgent
+from src.feather_ai.prompt import Prompt
+from src.feather_ai.utils import load_instruction_from_file
+
+load_dotenv()
+
+models = ["claude-haiku-4-5", "gpt-5-nano", "gemini-2.5-flash-lite", "mistral-small-2506"]
+models_small = ["gemini-2.5-flash-lite"]
+files = ["text_file.txt", "ocr_pdf_test.pdf", "ocr_image_test.jpeg"]
+
+class Response(BaseModel):
+    answer: str = Field(..., description="The answer to the question")
+    confidence: float = Field(..., description="How confident from 0-1 you are in your answer")
+def get_weather(location: str):
+    return f"The weather in {location} is rainy today."
+
+def test_base_agent():
+    question = "What is the capital of France?"
+    print(question)
+    for model in models:
+        agent = AIAgent(model, instructions=load_instruction_from_file("test_instructions.txt"))
+        resp = agent.run("What is the capital of France?")
+        print(f"{model}: {resp.content}")
+
+def test_multimodal():
+    for model in models:
+        print("-"*10 + f"Testing {model}" + "-"*10)
+        prompt = Prompt(
+            text="Please summarize the following documents each in 1 sentence",
+            documents=[os.path.join("test_docs", file) for file in files]
+        )
+        agent = AIAgent(model)
+        try:
+            resp = agent.run(prompt)
+        except ValueError as e:
+            print(f"xxx Error for model {model}: {e}")
+            continue
+        print(resp.content)
+
+def test_tool_calling():
+    print("=== Testing Tool calling ===")
+    for model in models_small:
+        agent = AIAgent(model, tools=[google_search])
+        resp = agent.run("What is the weather in Paris today? Use google search to find the answer.")
+        print(f"{model}: {resp.content}, Tool calls: {[str(tool_call) for tool_call in resp.tool_calls]}")
+        pprint(resp.input_messages)
+
+def test_structured_output():
+    print("=== Testing Structured Output ===")
+    for model in models:
+        agent = AIAgent(model, output_schema=Response)
+        resp = agent.run("What is the capital of France?")
+        pprint(f"{model}: {resp.content}")
+        assert isinstance(resp.content, Response)
+
+def test_tool_calling_with_structured_output():
+    print("=== Testing Tool calling with Structured Output ===")
+    for model in models_small:
+        agent = AIAgent(model, tools=[get_weather], output_schema=Response)
+        resp = agent.run("What is the weather in Paris today?")
+        pprint(f"{model}: {resp.content}")
+        assert isinstance(resp.content, Response)
+
+def test_multiple_tools():
+    print("=== Testing Multiple tools ===")
+    system_message = ("You are a helpful assistant that can interact with several tools."
+                      "You will be given a question and you must answer it using the tools you have."
+                      "First, just call the get_weather tool with the location as an argument."
+                      "Then once you get an answer, use the get_tips tool to provide some tips based on the weather.")
+    def get_tips(weather: str):
+        return f"If its {weather}, bring an umbrella!"
+    for model in models:
+        agent = AIAgent(model, instructions=system_message, tools=[get_weather, get_tips], output_schema=Response)
+        resp = agent.run("I am going to Paris today. What should I do?")
+        pprint(f"{model}: {resp.content}")
+        assert isinstance(resp.content, Response)
+
+async def test_complex_async_tooling():
+    print("=== Testing Multiple tools ===")
+    system_message = ("You are a helpful assistant that can interact with several tools."
+                      "You will be given a question and you must answer it using the tools you have."
+                      "First, just call the get_weather tool with the location as an argument."
+                      "Then once you get an answer, use the get_tips tool to provide some tips based on the weather.")
+
+    async def get_weather(location: str):
+        if location == "Munich":
+            return f"The weather in Munich is sunny today."
+        return f"The weather in {location} is rainy today."
+    async def get_tips(weather: str, location: str):
+        if weather == "sunny":
+            return f"Go for a walk in the english garden!"
+        return f"If its {weather} in {location}, bring an umbrella!"
+
+    agent = AIAgent("gemini-2.5-flash-lite", instructions=system_message, tools=[get_weather, get_tips], output_schema=Response)
+    resp = await agent.arun("Please check what my friends in Paris, Munich and Singapore should do today. Keep your answer in 3 short sentences.")
+    print(resp)
+    assert isinstance(resp.content, Response)
+
+def test_async_run():
+    async def test_run():
+        agent = AIAgent("claude-haiku-4-5")
+        resp = await agent.arun("What is the capital of France?")
+        print(resp.content)
+
+    asyncio.run(test_run())
+
+def test_complex_tools():
+    agent = AIAgent("gemini-2.5-flash-lite", tools=[*web_tools])
+    resp = agent.run("Search for a python code execution tool in langchain. Use google_search and then extract from the provided urls.")
+    print(resp)
+    print("--------------------------------")
+    pprint(resp.input_messages)
+
+async def test_async_complex_tools():
+    agent = AIAgent("gemini-2.5-flash-lite", tools=[code_execution_python, *web_tools_async])
+    resp = await agent.arun(""
+    "Please scrape this base url: https://docs.langchain.com/oss/python/langchain"
+                            "and this: https://google.github.io/adk-docs/ for a code execution tool in both frameworks. Give me an overview which one is easier to use.")
+    print(resp)
+    print("--------------------------------")
+    pprint(resp.input_messages)
+
+
+if __name__ == "__main__":
+    asyncio.run(test_async_complex_tools())