ant-ai 1.0.0__tar.gz

ant_ai-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 IDeA Group at IDSIA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ant_ai-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: ant-ai
+Version: 1.0.0
+Summary: ANT AI
+Author: Cezar Sas, Vincenzo Giuffrida, Sandra Mitrovic, Matteo Salani
+Author-email: Cezar Sas <cezar.sas@supsi.ch>, Vincenzo Giuffrida <vincenzo.giuffrida@supsi.ch>, Sandra Mitrovic <sandra.mitrovic@supsi.ch>, Matteo Salani <matteo.salani@supsi.ch>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Dist: a2a-sdk[sql,http-server,grpc,encryption,telemetry]>=1.0.0
+Requires-Dist: fastapi>=0.136.0
+Requires-Dist: litellm>=1.83.10
+Requires-Dist: loguru>=0.7.3
+Requires-Dist: mcp>=1.27.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: starlette>=1.0.0
+Requires-Dist: uvicorn>=0.44.0
+Requires-Dist: langfuse>=4.3.1 ; extra == 'langfuse'
+Requires-Dist: openai>=2.24.0 ; extra == 'openai'
+Requires-Python: >=3.14
+Provides-Extra: langfuse
+Provides-Extra: openai
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/ant_h_white.png">
+  <img alt="ANT AI" src="docs/assets/ant_h_dark.png" height="100">
+</picture>
+
+![Python](https://img.shields.io/badge/python-3.14%2B-4584b6?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/license-MIT-blue?logo=MIT&logoColor=white-lightgrey)
+[![Coverage main](https://gitlab-core.supsi.ch/dti-idsia/intsys/ant-ai/badges/main/coverage.svg)](https://gitlab-core.supsi.ch/dti-idsia/intsys/ant-ai/-/commits/main)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-526cfe?logo=materialformkdocs&logoColor=white)](https://ant-ai-27f99d.pages-core.supsi.ch)
+
+**A lightweight Python framework for building tool-driven AI agents and multi-agent systems.**
+
+</div>
+
+---
+
+ANT AI provides a composable set of primitives for building production-ready AI agents: a ReAct reasoning loop, a flexible tool system with MCP support, a graph-based workflow engine, and first-class agent-to-agent (A2A) communication via the [A2A protocol](https://github.com/a2aproject/A2A).
+
+## Features
+
+- **ReAct agent** — built-in Reason→Act loop with streaming, structured output, and configurable retry logic
+- **Flexible tools** — define tools as decorated functions, class namespaces, or load them directly from any [MCP](https://modelcontextprotocol.io/) server
+- **Workflow engine** — graph-based orchestration with static and conditional edges to sequence agent behaviour predictably
+- **Multi-agent colony** — wire agents together with the A2A protocol; each agent becomes a callable tool to its peers
+- **LLM-agnostic** — ships with [LiteLLM](https://github.com/BerriAI/litellm) and native OpenAI backends; any `ChatLLM`-conforming implementation works
+- **Observability** — structured lifecycle events with [Langfuse](https://langfuse.com/), OpenTelemetry, and log sinks
+- **Lifecycle hooks** — intercept and control every LLM call: pass, block, retry, or substitute results; ships with a [GuardrailsAI](https://www.guardrailsai.com/) adapter
+
+## Installation
+
+Requires Python 3.14+. Install with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add ant-ai
+```
+
+Or clone and sync for local development:
+
+```sh
+git clone <repo-url>
+cd ant-ai
+uv sync --all-extras
+```
+
+## Quickstart
+
+### Single agent
+
+```python
+from ant_ai import Agent, Message, State, tool
+from ant_ai.llm.integrations import LiteLLMChat
+
+@tool
+def get_weather(city: str) -> str:
+    """Return the current weather for a city."""
+    return f"Sunny, 22°C in {city}"
+
+llm = LiteLLMChat(model="gpt-4o-mini")
+
+agent = Agent(
+    name="WeatherAgent",
+    system_prompt="You are a helpful weather assistant.",
+    llm=llm,
+    tools=[get_weather],
+)
+
+state = State(messages=[Message(role="user", content="What's the weather in Lugano?")])
+answer = agent.invoke(state)
+print(answer)
+```
+
+### Streaming events
+
+```python
+from ant_ai.core import FinalAnswerEvent
+
+async for event in agent.stream(state):
+    if isinstance(event, FinalAnswerEvent):
+        print(event.content)
+```
+
+### Structured output
+
+```python
+from pydantic import BaseModel
+
+class WeatherReport(BaseModel):
+    city: str
+    temperature: int
+    condition: str
+
+answer = agent.invoke(state, response_schema=WeatherReport)
+# answer is a JSON string matching WeatherReport
+```
+
+## Development
+
+```sh
+# Install dev dependencies and pre-commit hooks
+uv sync --all-extras
+uv run pre-commit install
+
+# Run tests
+uv run pytest
+
+# Serve docs locally
+uv run mkdocs serve
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributing guide, branching model, and review process.
+
+## License
+
+This software is licensed under the MIT license. See the [LICENSE](LICENSE) file for details.

ant_ai-1.0.0/README.md

@@ -0,0 +1,116 @@
+<div align="center">
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/ant_h_white.png">
+  <img alt="ANT AI" src="docs/assets/ant_h_dark.png" height="100">
+</picture>
+
+![Python](https://img.shields.io/badge/python-3.14%2B-4584b6?logo=python&logoColor=white)
+![License](https://img.shields.io/badge/license-MIT-blue?logo=MIT&logoColor=white-lightgrey)
+[![Coverage main](https://gitlab-core.supsi.ch/dti-idsia/intsys/ant-ai/badges/main/coverage.svg)](https://gitlab-core.supsi.ch/dti-idsia/intsys/ant-ai/-/commits/main)
+[![Docs](https://img.shields.io/badge/docs-mkdocs-526cfe?logo=materialformkdocs&logoColor=white)](https://ant-ai-27f99d.pages-core.supsi.ch)
+
+**A lightweight Python framework for building tool-driven AI agents and multi-agent systems.**
+
+</div>
+
+---
+
+ANT AI provides a composable set of primitives for building production-ready AI agents: a ReAct reasoning loop, a flexible tool system with MCP support, a graph-based workflow engine, and first-class agent-to-agent (A2A) communication via the [A2A protocol](https://github.com/a2aproject/A2A).
+
+## Features
+
+- **ReAct agent** — built-in Reason→Act loop with streaming, structured output, and configurable retry logic
+- **Flexible tools** — define tools as decorated functions, class namespaces, or load them directly from any [MCP](https://modelcontextprotocol.io/) server
+- **Workflow engine** — graph-based orchestration with static and conditional edges to sequence agent behaviour predictably
+- **Multi-agent colony** — wire agents together with the A2A protocol; each agent becomes a callable tool to its peers
+- **LLM-agnostic** — ships with [LiteLLM](https://github.com/BerriAI/litellm) and native OpenAI backends; any `ChatLLM`-conforming implementation works
+- **Observability** — structured lifecycle events with [Langfuse](https://langfuse.com/), OpenTelemetry, and log sinks
+- **Lifecycle hooks** — intercept and control every LLM call: pass, block, retry, or substitute results; ships with a [GuardrailsAI](https://www.guardrailsai.com/) adapter
+
+## Installation
+
+Requires Python 3.14+. Install with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add ant-ai
+```
+
+Or clone and sync for local development:
+
+```sh
+git clone <repo-url>
+cd ant-ai
+uv sync --all-extras
+```
+
+## Quickstart
+
+### Single agent
+
+```python
+from ant_ai import Agent, Message, State, tool
+from ant_ai.llm.integrations import LiteLLMChat
+
+@tool
+def get_weather(city: str) -> str:
+    """Return the current weather for a city."""
+    return f"Sunny, 22°C in {city}"
+
+llm = LiteLLMChat(model="gpt-4o-mini")
+
+agent = Agent(
+    name="WeatherAgent",
+    system_prompt="You are a helpful weather assistant.",
+    llm=llm,
+    tools=[get_weather],
+)
+
+state = State(messages=[Message(role="user", content="What's the weather in Lugano?")])
+answer = agent.invoke(state)
+print(answer)
+```
+
+### Streaming events
+
+```python
+from ant_ai.core import FinalAnswerEvent
+
+async for event in agent.stream(state):
+    if isinstance(event, FinalAnswerEvent):
+        print(event.content)
+```
+
+### Structured output
+
+```python
+from pydantic import BaseModel
+
+class WeatherReport(BaseModel):
+    city: str
+    temperature: int
+    condition: str
+
+answer = agent.invoke(state, response_schema=WeatherReport)
+# answer is a JSON string matching WeatherReport
+```
+
+## Development
+
+```sh
+# Install dev dependencies and pre-commit hooks
+uv sync --all-extras
+uv run pre-commit install
+
+# Run tests
+uv run pytest
+
+# Serve docs locally
+uv run mkdocs serve
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contributing guide, branching model, and review process.
+
+## License
+
+This software is licensed under the MIT license. See the [LICENSE](LICENSE) file for details.

ant_ai-1.0.0/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12"]
+build-backend = "uv_build"
+
+[project]
+name = "ant-ai"
+version = "1.0.0"
+description = "ANT AI"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.14"
+authors = [
+    { name = "Cezar Sas", email = "cezar.sas@supsi.ch" },
+    { name = "Vincenzo Giuffrida", email = "vincenzo.giuffrida@supsi.ch" },
+    { name = "Sandra Mitrovic", email = "sandra.mitrovic@supsi.ch" },
+    { name = "Matteo Salani", email = "matteo.salani@supsi.ch" },
+]
+
+classifiers = [
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "a2a-sdk[sql,http-server,grpc,encryption,telemetry]>=1.0.0",
+    "fastapi>=0.136.0",
+    "litellm>=1.83.10",
+    "loguru>=0.7.3",
+    "mcp>=1.27.0",
+    "pydantic>=2.12.5",
+    "starlette>=1.0.0",
+    "uvicorn>=0.44.0",
+]
+
+[project.optional-dependencies]
+langfuse = ["langfuse>=4.3.1"]
+openai = ["openai>=2.24.0"]
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.5.1",
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=7.1.0",
+    "ruff>=0.15.11",
+    "ty>=0.0.32",
+]
+docs = [
+    "griffe-pydantic>=1.3.1",
+    "mkdocs>=1.6.1",
+    "mkdocs-awesome-nav>=3.3.0",
+    "mkdocs-gen-files>=0.6.1",
+    "mkdocs-literate-nav>=0.6.3",
+    "mkdocs-material>=9.7.6",
+    "mkdocs-panzoom-plugin>=0.5.2",
+    "mkdocs-section-index>=0.3.12",
+    "mkdocstrings[python]>=1.0.4",
+]
+
+[tool.uv]
+exclude-newer = "P2D" # Wait for the package to be up for at least 2 days before updating to it.

ant_ai-1.0.0/src/ant_ai/__init__.py

@@ -0,0 +1,43 @@
+from ant_ai.agent import Agent, BaseAgent
+from ant_ai.core import (
+    AnyEvent,
+    AnyMessage,
+    ChatLLMResponse,
+    Event,
+    InvocationContext,
+    Message,
+    State,
+    StepResult,
+    configure_logging,
+)
+from ant_ai.observer import CompositeSink, ObservabilitySink, obs
+from ant_ai.tools import Tool, ToolRegistry
+from ant_ai.tools.tool import tool
+from ant_ai.workflow import BaseAction, Workflow
+
+__all__ = [
+    # agent
+    "Agent",
+    "BaseAgent",
+    # core
+    "Message",
+    "AnyMessage",
+    "Event",
+    "AnyEvent",
+    "State",
+    "InvocationContext",
+    "ChatLLMResponse",
+    "StepResult",
+    "configure_logging",
+    # observer
+    "obs",
+    "ObservabilitySink",
+    "CompositeSink",
+    # tools
+    "Tool",
+    "tool",
+    "ToolRegistry",
+    # workflow
+    "Workflow",
+    "BaseAction",
+]

ant_ai-1.0.0/src/ant_ai/a2a/__init__.py

@@ -0,0 +1,23 @@
+from ant_ai.a2a.agent import A2AAgentTool
+from ant_ai.a2a.client import A2AClient, AgentClientError
+from ant_ai.a2a.colony import AgentSpec, Colony
+from ant_ai.a2a.config import A2AConfig
+from ant_ai.a2a.context_builder import HistoryRequestContextBuilder
+from ant_ai.a2a.executor import A2AExecutor
+from ant_ai.a2a.server import A2AServer
+from ant_ai.a2a.session import current_session_id
+from ant_ai.a2a.types import A2AMetadata
+
+__all__ = [
+    "A2AAgentTool",
+    "A2AClient",
+    "AgentClientError",
+    "Colony",
+    "AgentSpec",
+    "A2AConfig",
+    "HistoryRequestContextBuilder",
+    "A2AExecutor",
+    "A2AServer",
+    "current_session_id",
+    "A2AMetadata",
+]

ant_ai-1.0.0/src/ant_ai/a2a/agent.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+from collections.abc import Awaitable
+from typing import Any, Literal, overload
+
+from a2a.types import AgentCard
+from pydantic import Field, PrivateAttr, model_validator
+
+from ant_ai.a2a.client import A2AClient
+from ant_ai.a2a.config import A2AConfig
+from ant_ai.a2a.session import current_session_id
+from ant_ai.core.events import ClarificationNeededEvent, FinalAnswerEvent
+from ant_ai.tools.tool import Tool
+
+
+class A2AAgentTool(Tool):
+    """
+    A tool that provides an interface to interact with the Agent via the A2A protocol.
+    """
+
+    config: A2AConfig = Field(..., description="Configuration for the A2A client.")
+    agent_input_description: str = Field(
+        default="Message to send to the agent. Contains all the necessary information to answer the question in a clear way.",
+        description="Description of the input to the agent. This description will be used by the agent to generate the prompt for remote agent request.",
+    )
+
+    _a2a: A2AClient | None = PrivateAttr(default=None)
+    _initialized: bool = PrivateAttr(default=False)
+    _agent_card: AgentCard | None = PrivateAttr(default=None)
+    _last_task_id: str | None = PrivateAttr(default=None)
+
+    @model_validator(mode="after")
+    def _set_defaults(self) -> A2AAgentTool:
+        return self
+
+    def _ensure_a2a(self) -> None:
+        if self._a2a is None:
+            self._a2a = A2AClient(config=self.config)
+            self._a2a._agent_card: AgentCard | None = self._agent_card
+
+    def _init_metadata(self, agent_card: AgentCard) -> None:
+        """Set Tool metadata exactly once from an AgentCard."""
+        if not self.name:
+            self.name: str = agent_card.name
+        if not self.description:
+            self.description: str = self._create_agent_description(agent_card)
+
+        self.parameters: dict[str, Any] = {
+            "type": "object",
+            "properties": {
+                "message": {
+                    "type": "string",
+                    "description": (self.agent_input_description),
+                }
+            },
+            "required": ["message"],
+        }
+
+    async def _ensure_initialized(self) -> None:
+        """Fetch AgentCard (if needed) and set metadata/_func exactly once."""
+        if self._initialized:
+            return
+
+        self._ensure_a2a()
+        if self._a2a is None:
+            raise RuntimeError("A2A client not initialized")
+
+        agent_card: AgentCard = self._agent_card or await self._a2a.get_agent_card()
+        self._agent_card: AgentCard = agent_card
+        self._init_metadata(agent_card)
+
+        self._attach_func()
+        self._initialized = True
+
+    def _attach_func(self) -> None:
+        """Attach the call function to the _func (single callable Tool)."""
+
+        async def _call_remote(message: str) -> str:
+            await self._ensure_initialized()
+            self._ensure_a2a()
+            if self._a2a is None:
+                raise RuntimeError("A2A client not initialized")
+
+            last_text: str = ""
+            async for ev in self._a2a.send_message(
+                message, context_id=current_session_id.get(None)
+            ):
+                if ev.content:
+                    last_text: str = ev.content
+                if isinstance(ev, (FinalAnswerEvent, ClarificationNeededEvent)):
+                    break
+            return last_text
+
+        self._func = _call_remote
+
+    @overload
+    @classmethod
+    def from_config(cls, config: A2AConfig, agent_card: AgentCard) -> A2AAgentTool:
+        """Creates an A2A agent tool from a configuration and an agent card.
+
+        Returns:
+            An A2A agent tool.
+        """
+        ...
+
+    @overload
+    @classmethod
+    def from_config(
+        cls, config: A2AConfig, agent_card: None = None
+    ) -> Awaitable[A2AAgentTool]:
+        """Creates an A2A agent tool from a configuration.
+
+        Args:
+            config: _description_
+            agent_card: _description_. Defaults to None.
+
+        Returns:
+            An awaitable of an A2A agent tool.
+        """
+        ...
+
+    @classmethod
+    def from_config(
+        cls, config: A2AConfig, agent_card: AgentCard | None = None
+    ) -> A2AAgentTool | Awaitable[A2AAgentTool]:
+        """Creates an A2A agent tool from a configuration and an optional agent card. If no agent card is provided, the tool will be initialized asynchronously and the tool will be returned as an awaitable tool.
+
+        Args:
+            config: _description_
+            agent_card: _description_. Defaults to None.
+
+        Returns:
+            An A2A agent tool or an awaitable of an A2A agent tool.
+        """
+        tool: A2AAgentTool = cls(name=None, description=None, config=config)
+
+        if agent_card is not None:
+            tool._agent_card: AgentCard = agent_card
+            tool._ensure_a2a()
+            tool._init_metadata(agent_card)
+            tool._attach_func()
+            tool._initialized = True
+            return tool
+
+        async def _build() -> A2AAgentTool:
+            await tool._ensure_initialized()
+            return tool
+
+        return _build()
+
+    def _create_agent_description(self, agent_card: AgentCard) -> str:
+        parts: list[str] = [
+            agent_card.description,
+        ]
+
+        if agent_card.skills:
+            parts += ["", "### Available Skills", ""]
+            for skill in agent_card.skills:
+                parts.append(f"**{skill.name}**")
+                parts.append(skill.description)
+                if skill.tags:
+                    parts.append(f"Tags: {', '.join(skill.tags)}")
+                examples = list(skill.examples) if skill.examples else []
+                if examples:
+                    parts.append("Examples:")
+                    for ex in examples:
+                        parts.append(f"  - {ex}")
+                parts.append("")
+
+        return "\n".join(parts)
+
+    @property
+    def is_namespace(self) -> Literal[False]:
+        return False
+
+    def _sid(self) -> str:
+        return current_session_id.get()