Metadata-Version: 2.4
Name: agenticstack
Version: 0.1.0
Summary: The WordPress of AI Agents - A modular, lightweight agentic framework
Project-URL: Homepage, https://agentstack.dev
Project-URL: Documentation, https://docs.agentstack.dev
Project-URL: Repository, https://github.com/agentstack/agentstack
Author: AgentStack Team
License: Proprietary
License-File: LICENSE
Keywords: agents,ai,framework,llm,modular
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: aiofiles>=23.0.0
Requires-Dist: click>=8.0.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Provides-Extra: all
Requires-Dist: anthropic>=0.18.0; extra == 'all'
Requires-Dist: boto3>=1.34.0; extra == 'all'
Requires-Dist: cohere>=5.0.0; extra == 'all'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all'
Requires-Dist: groq>=0.4.0; extra == 'all'
Requires-Dist: mistralai>=0.1.0; extra == 'all'
Requires-Dist: ollama>=0.1.0; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: redis>=5.0.0; extra == 'all'
Requires-Dist: tiktoken>=0.5.0; extra == 'all'
Requires-Dist: together>=1.0.0; extra == 'all'
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.18.0; extra == 'all-providers'
Requires-Dist: boto3>=1.34.0; extra == 'all-providers'
Requires-Dist: cohere>=5.0.0; extra == 'all-providers'
Requires-Dist: google-generativeai>=0.3.0; extra == 'all-providers'
Requires-Dist: groq>=0.4.0; extra == 'all-providers'
Requires-Dist: mistralai>=0.1.0; extra == 'all-providers'
Requires-Dist: ollama>=0.1.0; extra == 'all-providers'
Requires-Dist: openai>=1.0.0; extra == 'all-providers'
Requires-Dist: tiktoken>=0.5.0; extra == 'all-providers'
Requires-Dist: together>=1.0.0; extra == 'all-providers'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.18.0; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34.0; extra == 'bedrock'
Provides-Extra: cloud-providers
Requires-Dist: anthropic>=0.18.0; extra == 'cloud-providers'
Requires-Dist: cohere>=5.0.0; extra == 'cloud-providers'
Requires-Dist: google-generativeai>=0.3.0; extra == 'cloud-providers'
Requires-Dist: groq>=0.4.0; extra == 'cloud-providers'
Requires-Dist: mistralai>=0.1.0; extra == 'cloud-providers'
Requires-Dist: openai>=1.0.0; extra == 'cloud-providers'
Requires-Dist: tiktoken>=0.5.0; extra == 'cloud-providers'
Requires-Dist: together>=1.0.0; extra == 'cloud-providers'
Provides-Extra: cohere
Requires-Dist: cohere>=5.0.0; extra == 'cohere'
Provides-Extra: dev
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Provides-Extra: google
Requires-Dist: google-generativeai>=0.3.0; extra == 'google'
Provides-Extra: groq
Requires-Dist: groq>=0.4.0; extra == 'groq'
Provides-Extra: local-providers
Requires-Dist: ollama>=0.1.0; extra == 'local-providers'
Provides-Extra: mistral
Requires-Dist: mistralai>=0.1.0; extra == 'mistral'
Provides-Extra: ollama
Requires-Dist: ollama>=0.1.0; extra == 'ollama'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Requires-Dist: tiktoken>=0.5.0; extra == 'openai'
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == 'redis'
Provides-Extra: together
Requires-Dist: together>=1.0.0; extra == 'together'
Description-Content-Type: text/markdown

# 🤖 AgentStack

**The WordPress of AI Agents** - A modular, lightweight, plugin-first agentic framework that makes building AI agents as easy as WordPress makes building websites.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## ✨ Features

- 🧩 **Modular Architecture** - Plug-and-play components for skills, tools, memory, and more
- 🔌 **Plugin System** - Extend functionality with WordPress-style plugins
- 🧠 **Multi-Type Memory** - Conversation, long-term, semantic, and composite memory
- 📊 **Graph Workflows** - Visual, state-based workflow orchestration
- 🔍 **RAG Pipeline** - Built-in retrieval-augmented generation with reranking
- 👥 **Human-in-the-Loop** - Approval workflows, feedback, and intervention points
- 🤱 **Mother Agent** - AI-powered assistant to help you build agents
- 🔧 **12+ LLM Providers** - OpenAI, Anthropic, Google, Azure, and more
- 📝 **Type-Safe** - Full type hints and validation

## 🚀 Quick Start

### Installation

```bash
pip install agentstack
```

### Create Your First Agent

```python
from agentstack import Agent, skill
from agentstack.memory import ConversationMemory

@skill(id="greet", description="Greet the user")
async def greet(name: str = "friend") -> str:
    return f"Hello, {name}! How can I help you today?"

agent = Agent(
    name="GreeterBot",
    skills=[greet],
    memory=ConversationMemory(),
    model="gpt-4"
)

# Run interactively
agent.run()
```

### Using the CLI

```bash
# Create a new project
stack init my-agent

# Run your agent
cd my-agent
stack run

# Get help from Mother Agent
stack mother
```

## 📖 Documentation

### Core Concepts

| Concept                             | Description                              |
| ----------------------------------- | ---------------------------------------- |
| [Agent](docs/core/agent.md)         | The main entity that processes requests  |
| [Skills](docs/core/skills.md)       | Capabilities your agent can use          |
| [Tools](docs/core/tools.md)         | External integrations (web, files, code) |
| [Memory](docs/core/memory.md)       | Context and conversation history         |
| [Workflows](docs/core/workflows.md) | Multi-step process orchestration         |

### Modules

- **[Memory](docs/modules/memory.md)** - Conversation, buffer, window, long-term, composite
- **[RAG](docs/modules/rag.md)** - Document loading, chunking, retrieval, reranking
- **[Tools](docs/modules/tools.md)** - Built-in and custom tools
- **[Workflows](docs/modules/workflows.md)** - State graphs and execution
- **[HITL](docs/modules/hitl.md)** - Human-in-the-loop patterns
- **[Plugins](docs/modules/plugins.md)** - Creating and using plugins

### Guides

- [Getting Started](docs/guides/getting-started.md)
- [Building Your First Agent](docs/guides/first-agent.md)
- [Adding Memory](docs/guides/memory.md)
- [Using Tools](docs/guides/tools.md)
- [Creating Workflows](docs/guides/workflows.md)
- [RAG Implementation](docs/guides/rag.md)
- [Multi-Agent Systems](docs/guides/multi-agent.md)
- [Plugin Development](docs/guides/plugins.md)

## 🧱 Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                         AgentStack                          │
├─────────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Agent     │  │  MultiAgent │  │   Mother    │          │
│  │             │  │   System    │  │   Agent     │          │
│  └──────┬──────┘  └──────┬──────┘  └─────────────┘          │
│         │                │                                  │
│  ┌──────┴────────────────┴──────────────────────────────┐   │
│  │                    Core Modules                      │   │
│  ├──────────┬──────────┬──────────┬──────────┬──────────┤   │
│  │  Skills  │  Tools   │  Memory  │Workflows │   RAG    │   │
│  └──────────┴──────────┴──────────┴──────────┴──────────┘   │
│                                                             │
│  ┌──────────────────────────────────────────────────────┐   │
│  │                  Foundation Layer                    │   │
│  ├─────────┬─────────┬─────────┬─────────┬──────────────┤   │
│  │ Kernel  │ Vectors │ Tracing │ Guards  │Orchestrate   │   │
│  └─────────┴─────────┴─────────┴─────────┴──────────────┘   │
│                                                             │
│  ┌────────────────────────────────────────────────────────┐ │
│  │                   LLM Providers                        │ │
│  ├────────┬──────────┬────────┬────────┬──────────┬───────┤ │
│  │ OpenAI │Anthropic │ Google │ Azure  │ Cohere   │ More  │ │
│  └────────┴──────────┴────────┴────────┴──────────┴───────┘ │
└─────────────────────────────────────────────────────────────┘
```

## 📦 Examples

### Research Agent with RAG

```python
from agentstack import Agent, skill
from agentstack.rag import RAGPipeline, SemanticRetriever
from agentstack.tools import WebSearchTool, WebFetchTool

@skill(id="research", description="Research a topic")
async def research(topic: str) -> str:
    # Skill implementation
    pass

agent = Agent(
    name="Researcher",
    skills=[research],
    tools=[WebSearchTool(), WebFetchTool()],
    rag=RAGPipeline(retriever=SemanticRetriever()),
)
```

### Workflow with State Graph

```python
from agentstack.workflows import StateGraph, GraphExecutor

graph = StateGraph()

graph.add_node("analyze", analyze_function)
graph.add_node("process", process_function)
graph.add_node("output", output_function)

graph.add_edge("analyze", "process")
graph.add_conditional_edge("process", router_function)

graph.set_entry_point("analyze")
compiled = graph.compile()

executor = GraphExecutor()
result = await executor.run(compiled.graph, initial_state={})
```

### Multi-Agent Collaboration

```python
from agentstack import Agent, MultiAgent

researcher = Agent(name="Researcher", skills=[search])
writer = Agent(name="Writer", skills=[write])
reviewer = Agent(name="Reviewer", skills=[review])

team = MultiAgent(
    name="ContentTeam",
    agents=[researcher, writer, reviewer],
    strategy="sequential",
)

result = await team.run("Create an article about AI agents")
```

## 🔌 Creating Plugins

```python
from agentstack.plugins import Plugin
from agentstack.tools import tool

class WeatherPlugin(Plugin):
    name = "weather"
    version = "1.0.0"

    def on_load(self):
        self.register_tool(self._create_weather_tool())

    def _create_weather_tool(self):
        @tool(name="get_weather", description="Get weather for a city")
        async def get_weather(city: str) -> dict:
            # Implementation
            return {"city": city, "temp": 72}
        return get_weather
```

## 🤱 Mother Agent

The Mother Agent is your AI-powered development assistant:

```bash
# Interactive mode
stack mother

# Design an agent
stack mother build "I need a research agent"

# Validate your project
stack mother validate

# Generate from template
stack mother generate researcher --name MyResearcher
```

```python
from agentstack.mother import MotherAgent

mother = MotherAgent()

# Get help designing an agent
blueprint = await mother.help_build(
    "I need an agent that searches the web and summarizes articles"
)

# Validate configuration
result = mother.validate(config=my_config)

# Debug an error
analysis = mother.debug(agent, error)
```

## 🛠️ CLI Commands

| Command                        | Description          |
| ------------------------------ | -------------------- |
| `stack init <name>`            | Create a new project |
| `stack run`                    | Run the agent        |
| `stack mother`                 | Start Mother Agent   |
| `stack plugin list`            | List plugins         |
| `stack plugin install <name>`  | Install a plugin     |
| `stack tool list`              | List available tools |
| `stack workflow create <name>` | Create a workflow    |
| `stack validate`               | Validate project     |

## 🧪 Testing

```bash
# Run all tests
pytest tests/

# Run specific tests
pytest tests/test_memory.py

# Run with coverage
pytest --cov=agentstack tests/
```

## 📋 Requirements

- Python 3.10+
- Dependencies installed via pip

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests
5. Submit a pull request

## 📄 License

MIT License - see [LICENSE](LICENSE) for details.

## 🙏 Acknowledgments

AgentStack is inspired by the WordPress model of accessible, extensible software that empowers creators of all skill levels.

---

**Built with ❤️ by the AgentStack Team**

[Documentation](https://docs.agentstack.dev) • [GitHub](https://github.com/agentstack/agentstack) • [Discord](https://discord.gg/agentstack)
