Metadata-Version: 2.4
Name: artcafe-agent-framework
Version: 0.4.3
Summary: A flexible, modular framework for building intelligent, collaborative AI agents
Home-page: https://github.com/artcafeai/agent-framework
Author: ArtCafe Team
Author-email: "ArtCafe.ai" <support@artcafe.ai>
Maintainer-email: "ArtCafe.ai" <support@artcafe.ai>
License: MIT License
        
        Copyright (c) 2023-2025 ArtCafeAI
        
        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.
Project-URL: Homepage, https://artcafe.ai
Project-URL: Documentation, https://docs.artcafe.ai/agent-framework
Project-URL: Repository, https://github.com/artcafeai/artcafe-agent-framework
Project-URL: Bug Tracker, https://github.com/artcafeai/artcafe-agent-framework/issues
Project-URL: Changelog, https://github.com/artcafeai/artcafe-agent-framework/blob/main/CHANGELOG.md
Keywords: ai,agents,llm,framework,messaging,pubsub
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: websockets>=10.4
Requires-Dist: tiktoken>=0.3.3
Requires-Dist: cryptography>=38.0.0
Requires-Dist: nats-py>=2.5.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Provides-Extra: llm-providers
Requires-Dist: openai>=1.0.0; extra == "llm-providers"
Requires-Dist: boto3>=1.26.0; extra == "llm-providers"
Requires-Dist: anthropic>=0.20.0; extra == "llm-providers"
Provides-Extra: validation
Requires-Dist: marshmallow>=3.19.0; extra == "validation"
Requires-Dist: pydantic>=2.0.0; extra == "validation"
Provides-Extra: all
Requires-Dist: artcafe-agent-framework[dev,llm-providers,validation]; extra == "all"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# ArtCafe.ai Agent Framework

<div align="center">
  <img src="https://artcafe.ai/img/logo/artcafe-logo.png" alt="ArtCafe.ai Logo" width="200"/>
  <h3>A flexible, modular framework for building intelligent, collaborative AI agents</h3>
</div>

<div align="center">
  <a href="https://opensource.org/licenses/MIT">
    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
  </a>
  <a href="https://python.org">
    <img src="https://img.shields.io/badge/Python-3.8+-blue.svg" alt="Python 3.8+">
  </a>
  <img src="https://img.shields.io/badge/pypi-v0.4.3-blue" alt="PyPI version">
</div>

<br/>

## Overview

The Agent Framework is a key component of the ArtCafe.ai platform, providing the foundation for building intelligent agents that can:

- Communicate through a pub/sub messaging system
- Discover and collaborate with other agents
- Process complex data and make decisions
- Self-report status and health metrics
- Manage their own lifecycle (start, stop, pause, etc.)

The framework implements a clean, extensible architecture with well-defined interfaces and pluggable components, making it easy to customize and extend.

## 🚀 Quick Start

```python
import asyncio
from artcafe.framework import Client

# Create a client with NKey authentication
client = Client(
    name="my-client",
    nkey_seed="SUAIBDPBAUTWCWBKIO6XHQNINK5FWJW4OHLXC3HQ2KFE4PEJYQFN7MOVOA",  # From Dashboard
    account_id="your-account-id"  # From Dashboard > Settings
)

@client.on_message("events.tasks")
async def handle_message(subject, payload, envelope):
    # Process messages on this subject
    if "help" in payload.get("content", "").lower():
        await client.publish("events.responses", {
            "client_id": client.client_id,
            "content": "I can help with that!"
        })

# Run the client (includes automatic heartbeat)
asyncio.run(client.run())
```

**Key Concepts:**
- All agents are **peers** - no producer/consumer hierarchy
- Every agent receives **all messages** on subscribed channels
- Each agent **independently decides** how to process messages

See the [Quick Start Guide](docs/quick_start.md) for more examples.

## Key Features

### 🚀 Core Capabilities
- **NKey Authentication**: Ed25519 keys native to NATS for secure authentication
- **Direct NATS Connection**: No WebSocket layer, pure NATS pub/sub
- **Peer Messaging**: All clients are equal peers receiving subscribed messages
- **Decorator Handlers**: Easy message handling with `@client.on_message()`
- **Automatic Heartbeat**: Built-in connection health monitoring
- **Subject-Based Permissions**: Fine-grained publish/subscribe controls

### Core Features
- **Lightweight Agent Core**: Base agent classes with essential functionality
- **Flexible Messaging**: Multiple messaging backends (memory, pub/sub, NATS)
- **NATS Integration**: Scalable pub/sub architecture with hierarchical topics
- **LLM Integration**: Plug-and-play support for leading LLM providers
- **Tool Framework**: Decorator-based tool creation and registry
- **Workflow Patterns**: Pre-built patterns for chaining, routing, and parallelization
- **Event Loop Architecture**: Structured flow for agent-LLM interactions
- **Conversation Management**: Context window management for LLM interactions
- **MCP Support**: Integration with Model Context Protocol servers (including MCP over NATS)
- **A2A Protocol**: Agent-to-Agent negotiation and coordination
- **Telemetry & Tracing**: Built-in metrics collection and tracing

## Installation

```bash
# Install from PyPI (coming soon)
pip install artcafe-agent-framework

# Install from source
git clone https://github.com/artcafeai/agent-framework.git
cd agent-framework
pip install -e .

# Or install with optional dependencies
pip install -e ".[llm-providers,dev]"
```

## Quick Start

### Hello World Example

The absolute simplest way to create an agent:

```python
from framework import create_agent

# Create and run an agent in 3 lines
agent = create_agent("my-agent")

@agent.on_message("hello")
def say_hello(message):
    return {"response": f"Hello, {message.get('name', 'World')}!"}

agent.run()
```

### LLM-First Example

Start with an LLM and add capabilities:

```python
from framework import create_llm_agent

# Create an LLM agent with tools
agent = create_llm_agent(provider="anthropic", api_key="your-key")

@agent.tool
def search_web(query: str) -> str:
    """Search the web for information."""
    # Your search implementation
    return f"Search results for: {query}"

# Chat with the agent
response = await agent.chat("What's the weather in Paris?")
print(response)
```

### Verified Agent Example

Build reliable agents with verification:

```python
from framework import VerifiedAgent, verify_input, verify_output

class DataAgent(VerifiedAgent):
    @verify_input(lambda x: "data" in x)
    @verify_output(lambda x: x is not None)
    async def process_data(self, message):
        # Process with automatic verification
        return {"processed": message["data"].upper()}
```

## Architecture

The ArtCafe.ai Agent Framework is built on a modular architecture with these key components:

### Core Components

- **BaseAgent**: Abstract base class that defines the agent lifecycle and messaging patterns
- **EnhancedAgent**: Extension with integrated messaging, configuration, and advanced features
- **MessagingInterface**: Abstraction layer for all messaging operations
- **Provider Pattern**: Support for different messaging backends (in-memory, pub/sub)
- **LLM Integration**: Pluggable LLM providers (Anthropic, OpenAI, Bedrock)

### Directory Structure

```
/agent_framework/
├── agents/                 # Agent implementations
├── framework/              # Core framework code
│   ├── auth/               # Authentication providers
│   ├── conversation/       # Conversation management
│   ├── core/               # Base agent classes
│   ├── event_loop/         # Event loop architecture
│   ├── examples/           # Example agent implementations
│   ├── llm/                # LLM provider implementations
│   ├── mcp/                # Model Context Protocol
│   ├── messaging/          # Messaging providers
│   ├── telemetry/          # Metrics and tracing
│   └── tools/              # Tool decorator and registry
├── main.py                 # Main entry point
└── setup_agent.py          # Setup script
```

## NATS Integration

The framework now supports NATS as a scalable messaging backbone:

```python
from framework.core import NATSAgent, AgentConfig

# Create a NATS-enabled agent
config = AgentConfig({"nats.servers": ["nats://localhost:4222"]})
agent = NATSAgent(agent_id="my-agent", config=config)

# Use MCP over NATS
await agent.call_mcp_tool("remote-server", "search", {"query": "AI news"})

# A2A negotiations
result = await agent.negotiate_with_agents(
    ["agent-2", "agent-3"],
    "task_assignment",
    {"task": "process_data", "size": "10GB"}
)
```

See the [NATS Integration Guide](docs/nats_integration.md) for details.

## Advanced Topics

For more advanced usage, check out the example scripts in the `examples/` directory. These demonstrate:

- Building multi-agent systems with NATS
- Using MCP over NATS and A2A protocols
- Customizing LLM providers
- Creating tool libraries
- Implementing custom messaging backends
- Integrating with external services

## Contributing

We welcome contributions to the Agent Framework! Please see the [Contributing Guide](CONTRIBUTING.md) for details on how to get involved.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## About ArtCafe.ai

[ArtCafe.ai](https://artcafe.ai) is building the future of AI collaboration by providing tools, frameworks, and infrastructure for creating and deploying intelligent agent systems. Our mission is to make AI agents accessible, composable, and useful for real-world tasks.
