Metadata-Version: 2.4
Name: yaaaf
Version: 0.0.32
Summary: YAAAF (Yet Another Autonomous Agents Framework) - A modular framework for building intelligent agentic applications with Python backend and Next.js frontend
Author: fractalego
Maintainer: fractalego
License: MIT
Project-URL: Homepage, https://github.com/fractalego/yaaaf
Project-URL: Documentation, https://yaaaf.readthedocs.io
Project-URL: Repository, https://github.com/fractalego/yaaaf.git
Project-URL: Issues, https://github.com/fractalego/yaaaf/issues
Keywords: ai,agents,framework,orchestrator,chatbot,sql,visualization,web-search
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: bs4>=0.0.2
Requires-Dist: build>=1.2.2.post1
Requires-Dist: duckduckgo-search>=8.0.2
Requires-Dist: fastapi>=0.115.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: mdpd>=0.2.1
Requires-Dist: nltk>=3.9.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: pandas>=1.3.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-ai>=0.2.18
Requires-Dist: pydantic-settings>=2.8.1
Requires-Dist: pypdf2>=3.0.1
Requires-Dist: rank-bm25>=0.2.2
Requires-Dist: requests>=2.25.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: singleton-decorator>=1.0.0
Requires-Dist: tabulate>=0.8.0
Requires-Dist: uvicorn>=0.15.0
Provides-Extra: dev
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.18.0; extra == "dev"
Provides-Extra: mcp
Requires-Dist: pydantic-ai>=0.2.0; extra == "mcp"
Requires-Dist: pydantic-ai-slim[mcp]>=0.0.50; extra == "mcp"
Provides-Extra: nlp
Requires-Dist: nltk>=3.6.0; extra == "nlp"
Requires-Dist: rank-bm25>=0.2.0; extra == "nlp"
Provides-Extra: all
Requires-Dist: yaaaf[dev,mcp,nlp]; extra == "all"

# YAAAF - Yet Another Autonomous Agents Framework

YAAAF is a modular framework for building intelligent agentic applications with both Python backend and Next.js frontend components. The system features an orchestrator pattern with specialized agents for different tasks like SQL queries, web search, visualization, machine learning, and reflection.

## 🚀 Key Features

- **🤖 Modular Agent System**: Specialized agents for SQL, visualization, web search, ML, RAG, and more
- **🎯 Orchestrator Pattern**: Central coordinator that intelligently routes queries to appropriate agents
- **🔌 MCP Integration**: Full support for Model Context Protocol (MCP) with SSE and stdio transports
- **⚡ Real-time Streaming**: Live updates through WebSocket-like streaming with structured Note objects
- **📊 Artifact Management**: Centralized storage for generated content (tables, images, models, etc.)
- **🌐 Modern Frontend**: React-based UI with real-time chat interface and agent attribution
- **🔧 Extensible**: Easy to add new agents and capabilities with standardized interfaces
- **🏷️ Tag-Based Routing**: HTML-like tags for intuitive agent selection (`<sqlagent>`, `<visualizationagent>`, etc.)

## 🏗️ Architecture Overview

```
┌─────────────────┐    HTTP/REST     ┌──────────────────┐
│  Frontend       │ ◄──────────────► │  Backend         │
│  (Next.js)      │                  │  (FastAPI)       │
└─────────────────┘                  └──────────────────┘
                                              │
                                              ▼
                                    ┌──────────────────┐
                                    │  🔄 Orchestrator │
                                    │     Agent        │
                                    └──────────────────┘
                                              │
                        ┌─────────────────────┼─────────────────────┬─────────────────────┐
                        ▼                     ▼                     ▼                     ▼
              ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐   ┌─────────────────┐
              │ 🔄  TODO Agent  │   │ 🔄 SQL Agent    │   │ 🔄 Web Search   │   │ 🔄  ...         │
              │                 │   │                 │   │   Agent         │   │                 │
              └─────────────────┘   └─────────────────┘   └─────────────────┘   └─────────────────┘
                                              ▼                     ▼
                                    ┌─────────────────┐   ┌─────────────────┐
                                    │ Database source │   │ Search API      │
                                    │                 │   │                 │
                                    └─────────────────┘   └─────────────────┘
```

## 🚀 Quick Start

### Installation & Setup

```bash
# Clone the repository
git clone <repository-url>
cd agents_framework

# Install Python dependencies
pip install -r requirements.txt

# Install frontend dependencies
cd frontend
pnpm install
cd ..
```

### Running YAAAF

**Start the backend server** (default port 4000):
```bash
python -m yaaaf backend
```

**Start the frontend server** (default port 3000):
```bash
python -m yaaaf frontend
```

**Custom ports**:
```bash
python -m yaaaf backend 8080         # Backend on port 8080
python -m yaaaf frontend 3001        # Frontend on port 3001
```

**HTTPS Support**:
HTTPS mode is currently not fully supported in the standalone distribution. For HTTPS in production, use a reverse proxy like nginx:

```bash
# Start YAAAF on HTTP
python -m yaaaf frontend 3000

# Configure nginx with SSL to proxy to port 3000
```


### First Steps

1. Open your browser to `http://localhost:3000`
2. Start chatting with the AI system
3. Try these example queries:
   - "How many records are in the database?"
   - "Create a visualization of the sales data"
   - "Search for recent AI developments"
   - "Analyze customer demographics and show trends"

## 🤖 Available Agents

| Agent | Purpose | Usage Tag | Capabilities |
|-------|---------|-----------|-------------|
| **OrchestratorAgent** | Central coordinator | `<orchestratoragent>` | Routes queries, manages flow |
| **SqlAgent** | Database queries | `<sqlagent>` | Natural language to SQL, data retrieval |
| **VisualizationAgent** | Charts & graphs | `<visualizationagent>` | Matplotlib visualizations from data |
| **WebSearchAgent** | Web search | `<websearchagent>` | DuckDuckGo search integration |
| **ReflectionAgent** | Planning & reasoning | `<reflectionagent>` | Step-by-step problem breakdown |
| **RAGAgent** | Document retrieval | `<ragagent>` | Retrieval-augmented generation |
| **TodoAgent** | Task planning | `<todoagent>` | Creates structured todo lists for complex tasks |
| **MleAgent** | Machine learning | `<mleagent>` | sklearn model training & analysis |
| **ReviewerAgent** | Data analysis | `<revieweragent>` | Extract insights from artifacts |
| **ToolAgent** | External tools | `<toolagent>` | MCP (Model Context Protocol) integration - SSE & stdio |
| **BashAgent** | Filesystem operations | `<bashagent>` | File reading, writing, directory operations (with user confirmation) |

## 💡 Example Usage

### Simple Query
```python
from yaaaf.components.orchestrator_builder import OrchestratorBuilder
from yaaaf.components.data_types import Messages

orchestrator = OrchestratorBuilder().build()
messages = Messages().add_user_utterance("How many users are in the database?")
response = await orchestrator.query(messages)
```

### MCP Integration
```python
from yaaaf.connectors.mcp_connector import MCPSseConnector, MCPStdioConnector
from yaaaf.components.agents.tool_agent import ToolAgent
from yaaaf.components.client import OllamaClient

# SSE-based MCP server
sse_connector = MCPSseConnector(
    url="http://localhost:8080/sse",
    description="Math Tools Server"
)

# Stdio-based MCP server  
stdio_connector = MCPStdioConnector(
    command="python",
    args=["-m", "my_mcp_server"],
    description="Local MCP Server"
)

# Use with ToolAgent
client = OllamaClient(model="qwen2.5:32b")
tools = await sse_connector.get_tools()
tool_agent = ToolAgent(client=client, tools=[tools])

messages = Messages().add_user_utterance("Calculate the sum of 15 and 27")
response = await tool_agent.query(messages)
```

## 🛠️ Development

### Backend Development
```bash
# Run tests
python -m unittest discover tests/

# Code formatting
ruff format .
ruff check .

# Start with debugging
YAAAF_DEBUG=true python -m yaaaf backend

# Test MCP servers
python tests/mcp_sse_server.py --port 8080        # SSE server on port 8080
python tests/mcp_stdio_server.py                  # Stdio server
```

### Frontend Development
```bash
cd frontend

# Development server
pnpm dev

# Type checking
pnpm typecheck

# Linting & formatting
pnpm lint
pnpm format:write

# Build for production
pnpm build
```

## 📊 Data Flow

1. **User Input**: Query submitted through frontend chat interface
2. **Stream Creation**: Backend creates conversation stream
3. **Orchestration**: OrchestratorAgent analyzes query and routes to appropriate agents
4. **Agent Processing**: Specialized agents process their portions of the request
5. **Artifact Generation**: Agents create structured artifacts (tables, images, etc.)
6. **Note Creation**: Results packaged as Note objects with agent attribution
7. **Real-time Streaming**: Notes streamed back to frontend with live updates
8. **UI Rendering**: Frontend displays formatted responses with agent identification

## 🔧 Configuration

### LLM Requirements

**⚠️ Important**: YAAAF currently supports **Ollama only** for LLM integration. You must have Ollama installed and running on your system.

**Prerequisites:**
- Install [Ollama](https://ollama.ai/) on your system
- Download and run a compatible model (e.g., `ollama pull qwen2.5:32b`)
- Ensure Ollama is running (usually on `http://localhost:11434`)

YAAAF uses the `OllamaClient` for all LLM interactions. Support for other LLM providers (OpenAI, Anthropic, etc.) may be added in future versions.

### Environment Variables
- `YAAAF_CONFIG`: Path to configuration JSON file

### Configuration File
```json
{
  "client": {
    "model": "qwen2.5:32b",
    "temperature": 0.7,
    "max_tokens": 1024,
    "host": "http://localhost:11434"
  },
  "agents": [
    "reflection",
    {
      "name": "visualization",
      "model": "qwen2.5-coder:32b",
      "temperature": 0.1
    },
    "sql",
    {
      "name": "rag",
      "model": "qwen2.5:14b", 
      "temperature": 0.8,
      "max_tokens": 4096,
      "host": "http://localhost:11435"
    },
    "reviewer",
    "websearch",
    "url_reviewer",
    "bash",
    "tool"
  ],
  "sources": [
    {
      "name": "london_archaeological_data",
      "type": "sqlite",
      "path": "../../data/london_archaeological_data.db"
    }
  ],
  "tools": [
    {
      "name": "math_tools",
      "type": "sse",
      "description": "Mathematical calculation tools",
      "url": "http://localhost:8080/sse"
    },
    {
      "name": "file_tools",
      "type": "stdio",
      "description": "File manipulation tools",
      "command": "python",
      "args": ["-m", "my_file_server"]
    }
  ]
}
```

**Per-Agent Configuration:**
- **Simple format**: `"agent_name"` uses default client settings
- **Object format**: `{"name": "agent_name", "model": "...", "temperature": 0.1, "host": "..."}` overrides specific parameters
- **Fallback**: Any unspecified parameters use the default client configuration
- **Examples**: Use specialized models for specific tasks (e.g., coding models for visualization, larger models for RAG)
- **Host configuration**: Set different Ollama instances per agent or use default host

**MCP Tools Configuration:**
- **SSE Tools**: For HTTP-based MCP servers (`"type": "sse"` with `"url"`)
- **Stdio Tools**: For command-line MCP servers (`"type": "stdio"` with `"command"` and `"args"`)
- **Tool Agent**: Add `"tool"` to agents list to enable MCP tool integration
- **Description**: Human-readable description of what the tool server provides
- **Error Handling**: Failed tool connections are logged but don't prevent startup

## 📚 Documentation

Comprehensive documentation is available in the `documentation/` folder:

```bash
cd documentation
pip install -r requirements.txt
make html
open build/html/index.html
```

**Documentation includes:**
- 📖 Getting Started Guide
- 🏗️ Architecture Overview  
- 🤖 Agent Development Guide
- 🔌 API Reference
- 🌐 Frontend Development
- 💻 Development Practices
- 📋 Usage Examples

## 🧪 Testing

```bash
# Backend tests
python -m unittest discover tests/

# Specific agent tests
python -m unittest tests.test_sql_agent
python -m unittest tests.test_orchestrator_agent

# Frontend tests
cd frontend
pnpm test
```

## 🤝 Contributing

1. **Fork the repository**
2. **Create a feature branch**: `git checkout -b feature/amazing-feature`
3. **Follow code style**: Run `ruff format .` and `pnpm format:write`
4. **Add tests**: Ensure new features have test coverage
5. **Update docs**: Add documentation for new features
6. **Submit PR**: Create a pull request with clear description

## 📋 Requirements

**Backend:**
- Python 3.11+
- FastAPI
- Pydantic
- pandas
- matplotlib
- sqlite3

**Frontend:**
- Node.js 18+
- Next.js 14
- TypeScript
- Tailwind CSS
- pnpm

**Package Distribution:**
- The yaaaf wheel includes a complete standalone frontend (`yaaaf/client/standalone/`)
- No additional frontend setup required for basic usage
- Frontend source code available in `frontend/` for development

## 📄 License

MIT License (MIT)

## 🆘 Support

- 📖 **Documentation**: Check the `documentation/` folder
- 🐛 **Issues**: Report bugs via GitHub Issues
- 💬 **Discussions**: Join GitHub Discussions for questions

---

**YAAAF** - Building the future of agentic applications, one intelligent agent at a time! 🚀
