# SAGE Agentic Framework

**Independent package for agentic AI capabilities: planning, workflows, and agent coordination**

[![PyPI version](https://badge.fury.io/py/isage-agentic.svg)](https://badge.fury.io/py/isage-agentic)
[![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)

> **📢 Note**: Tool selection algorithms have been moved to [`sage-agentic-tooluse`](https://github.com/intellistream/sage-agentic-tooluse) for focused development.

## 🎯 Overview

`sage-agentic` provides a comprehensive framework for building agentic AI systems with:

- **Planning Algorithms**: ReAct, Tree of Thoughts (ToT), hierarchical planning
- **Workflow Management**: Workflow orchestration and optimization
- **Agent Coordination**: Multi-agent collaboration and registry
- **Reasoning**: Advanced reasoning capabilities and timing decisions

## 📦 Installation

```bash
# Basic installation
pip install isage-agentic

# With LLM support
pip install isage-agentic[llm]

# Development installation
pip install isage-agentic[dev]
```

## 🔧 Tool Selection (Moved to sage-agentic-tooluse)

**Tool selection algorithms are now in a separate package:**

- **Repository**: https://github.com/intellistream/sage-agentic-tooluse
- **Install**: `pip install isage-agentic-tooluse`
- **Import**: `from sage_libs.sage_agentic_tooluse import ...`

```python
# Tool selection - use sage-agentic-tooluse package
from sage_libs.sage_agentic_tooluse import (
    KeywordToolSelector,
    EmbeddingToolSelector,
    HybridToolSelector,
    DFSDTToolSelector,
    GorillaAdapter,
)
```

**Why separate tool selection?**
- Focused development by dedicated team
- Rapid iteration with independent versioning
- Can be used outside SAGE ecosystem

## 🚀 Quick Start

### Planning

```python
from sage_libs.sage_agentic.agents.planning import ReActPlanner

# Create planner
planner = ReActPlanner(llm=your_llm_client)

# Generate plan
plan = planner.plan(
    task="Analyze this document and summarize key findings",
    context={"document": doc_content}
)
```

### Workflow Management

```python
from sage_libs.sage_agentic.workflow import WorkflowEngine

# Create workflow
workflow = WorkflowEngine()

# Register and execute workflows
workflow.register("data_pipeline", pipeline_config)
result = workflow.execute("data_pipeline", inputs=data)
```

### Intent Recognition

```python
from sage_libs.sage_agentic.agents.intent import IntentClassifier

# Create intent classifier
classifier = IntentClassifier()

# Classify user intent
intent = classifier.classify("Show me the sales report for last month")
```

## 📚 Key Components

### 1. **Planning** (`agents/planning/`)

Planning algorithms and strategies:

- **ToT (Tree of Thoughts)**: Multi-path reasoning with backtracking
- **ReAct**: Reasoning + Acting interleaved execution
- **Hierarchical Planner**: Hierarchical task decomposition
- **Dependency Graph**: Task dependency management
- **Timing Decider**: Execution timing optimization

### 2. **Workflow** (`workflow/`, `workflows/`)

Workflow orchestration capabilities:

- **Workflow Engine**: Execute multi-step workflows
- **Workflow Nodes**: Define workflow components
- **Workflow Edges**: Connect workflow steps
- **Optimization**: Workflow optimization strategies

### 3. **Reasoning** (`reasoning/`)

Advanced reasoning capabilities:

- **Chain of Thought**: Step-by-step reasoning
- **Reflection**: Self-evaluation and correction
- **Meta-reasoning**: Reasoning about reasoning processes

### 4. **Evaluation** (`eval/`)

Agent evaluation capabilities:
- Metrics tracking
- Determinism testing
- Telemetry and monitoring

### 5. **Interfaces & Registry** (`interface/`, `interfaces/`, `registry/`)

Unified interfaces and registration system for:
- Planners
- Workflows
- Agents
- Intent classifiers

## 🔧 Architecture

```
sage_libs/sage_agentic/
├── agents/                 # Agent implementations
│   ├── planning/          # Planning algorithms (ReAct, ToT, etc.)
│   ├── intent/            # Intent detection and classification
│   ├── bots/              # Bot implementations
│   ├── runtime/           # Runtime execution
│   └── profile/           # Agent profiles
├── workflow/              # Workflow orchestration
├── workflows/             # Workflow implementations
├── reasoning/             # Reasoning capabilities
├── eval/                  # Evaluation tools
├── interface/             # Protocol definitions
├── interfaces/            # Interface implementations
└── registry/              # Component registry
```

## 🎓 Use Cases

1. **Multi-Agent Systems**: Build coordinated multi-agent workflows
2. **Complex Task Planning**: Decompose tasks with hierarchical planning
3. **Adaptive Workflows**: Dynamic workflow execution with reasoning
4. **Intent-Driven Systems**: Classify and route based on user intent
5. **Research**: Experiment with different planning strategies

## 🔗 Integration with SAGE

This package is part of the SAGE ecosystem but can be used independently:

```python
# Standalone usage
from sage_libs.sage_agentic import ReActPlanner

# With SAGE interface layer (if installed)
from sage.libs.agentic import ReActPlanner
```

## Related Packages

- **[sage-agentic-tooluse](https://github.com/intellistream/sage-agentic-tooluse)**: Tool selection algorithms
- **[sage-agentic-tooluse-benchmark](https://github.com/intellistream/sage-agentic-tooluse-benchmark)**: Tool selection evaluation

## 📖 Documentation

- **Repository**: https://github.com/intellistream/sage-agentic
- **SAGE Documentation**: https://intellistream.github.io/SAGE-Pub/
- **Issues**: https://github.com/intellistream/sage-agentic/issues

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

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

## 🙏 Acknowledgments

Part of the [SAGE](https://github.com/intellistream/SAGE) ecosystem for stream analytics and generative AI.

## 📧 Contact

- **Team**: IntelliStream Team
- **Email**: shuhao_zhang@hust.edu.cn
- **GitHub**: https://github.com/intellistream

---

**Part of the SAGE ecosystem** - Stream Analytics for Generative AI Engines
