Metadata-Version: 2.4
Name: palette-multi-agent
Version: 0.1.0
Summary: A configurable multi-agent orchestration framework built with LangGraph
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Requires-Dist: PyQt6>=6.7
Requires-Dist: langgraph
Requires-Dist: langchain-core
Requires-Dist: langchain-ollama
Requires-Dist: langchain-openai
Requires-Dist: langchain-anthropic
Requires-Dist: python-dotenv

# 🎨 Palette — Multi-Agent Orchestration Framework

**Build, configure, and run multi-agent AI workflows with ease.**

Palette is a configurable multi-agent orchestration framework built using **Python and LangGraph**. It allows users to create AI agents, organize them into layers, configure different LLM providers, and execute workflows through a simple graphical interface.

Instead of manually writing complex agent workflows, you can define your agents and their responsibilities in a YAML configuration file.

---

## ✨ Features

- **Visual GUI:** Configure and run multi-agent workflows through a PyQt6 interface.
- **Dynamic Agent Creation:** Create agents using configuration instead of hardcoding them.
- **Layer-Based Architecture:** Organize agents into multiple execution layers.
- **Multiple LLM Providers:** Supports Ollama, OpenAI, and Anthropic.
- **Flexible Model Configuration:** Configure each agent's model, temperature, role, and instructions.
- **Agent Communication:** Agents can access outputs generated by previous agents.
- **Final Answer Generation:** A final agent can combine previous outputs into one response.
- **Dynamic LangGraph Workflow:** Build graph structures automatically from YAML.
- **YAML Configuration:** Save, load, and customize workflows.
- **Error Handling:** Handles provider errors, missing API keys, model errors, and quota issues.

---

## 🏗️ How Palette Works

Palette follows a layer-based multi-agent architecture.

Each layer contains one or more agents that perform specific tasks.

Example workflow:

```text
             USER INPUT
                  |
                  v
          +---------------+
          |    Layer 1    |
          |  Lead Agent   |
          +---------------+
                  |
                  v
       +---------------------+
       |      Layer 2        |
       |                     |
       |  Researcher         |
       |  Reviewer           |
       +---------------------+
                  |
                  v
          +---------------+
          |    Layer 3    |
          | Final Agent   |
          +---------------+
                  |
                  v
             FINAL OUTPUT
```

### Layer Rules

| Layer | Maximum agents |
|---|---:|
| Layer 1 | 1 |
| Layer 2 onwards | 2 per layer |

Users can define the number of layers and assign agents to each layer.

---

## 🛠️ Technology Stack

| Technology | Purpose |
|---|---|
| Python | Core programming language |
| LangGraph | Agent workflow orchestration |
| LangChain | LLM integration |
| PyQt6 | Graphical user interface |
| PyYAML | YAML configuration |
| Ollama | Local LLM execution |
| OpenAI API | Cloud LLM integration |
| Anthropic API | Cloud LLM integration |

---

## 📦 Installation

### Option 1: Install using pip

After Palette is published on PyPI:

```bash
pip install palette-multi-agent
```

Launch the graphical interface:

```bash
palette
```

### Option 2: Install from source

Clone the repository:

```bash
git clone YOUR_GITHUB_REPOSITORY_URL
```

Navigate to the project directory:

```bash
cd palette
```

Create a virtual environment:

```bash
python -m venv venv
```

Activate it on Windows:

```powershell
.\venv\Scripts\activate
```

Activate it on Linux/macOS:

```bash
source venv/bin/activate
```

Install the project:

```bash
pip install -e .
```

Launch Palette:

```bash
palette
```

---

## ⚙️ Configuration

Palette uses YAML to define agents and workflow layers.

Example `config.yaml`:

```yaml
task: "Explain Machine Learning to a beginner."

agents:

  head:
    provider: openai
    model: gpt-4o-mini
    temperature: 0.3
    role: "Lead AI"
    instructions: >
      Understand the user's question
      and provide useful context.

  researcher:
    provider: ollama
    model: qwen2:1.5b
    temperature: 0.7
    role: "Researcher"
    instructions: >
      Provide detailed and accurate
      information about the question.

  reviewer:
    provider: ollama
    model: qwen2:1.5b
    temperature: 0.5
    role: "Reviewer"
    instructions: >
      Review previous outputs and
      identify mistakes or missing information.

  final:
    provider: ollama
    model: qwen2:1.5b
    temperature: 0.3
    role: "Final Answer Generator"
    final: true
    instructions: >
      Combine previous outputs into
      one clear and complete answer.

layers:

  - name: layer_1
    agents:
      - head

  - name: layer_2
    agents:
      - researcher
      - reviewer

  - name: layer_3
    agents:
      - final
```

### Agent Configuration Parameters

| Parameter | Description |
|---|---|
| `provider` | LLM provider: ollama, openai, or anthropic |
| `model` | Model identifier |
| `temperature` | Controls response randomness |
| `role` | Agent's responsibility |
| `instructions` | Instructions given to the agent |
| `final` | Marks the final-answer agent when set to `true` |

The `task` field contains the user's question or task.

---

## 🔑 API Key Configuration

Palette does not require users to share API keys with the project developer.

Each user should configure their own API keys.

### OpenAI

Set the environment variable:

**Windows PowerShell:**

```powershell
$env:OPENAI_API_KEY="your_openai_api_key"
```

**Linux/macOS:**

```bash
export OPENAI_API_KEY="your_openai_api_key"
```

### Anthropic

**Windows PowerShell:**

```powershell
$env:ANTHROPIC_API_KEY="your_anthropic_api_key"
```

**Linux/macOS:**

```bash
export ANTHROPIC_API_KEY="your_anthropic_api_key"
```

You can also use a personal `.env` file with `python-dotenv`.

Never upload real API keys to GitHub or PyPI.

---

## 🦙 Using Ollama (Local LLM)

Ollama allows users to run supported language models locally.

### Step 1: Install Ollama

Download it from:

https://ollama.com/download

### Step 2: Download a model

```bash
ollama pull qwen2:1.5b
```

### Step 3: Start the Ollama server

```bash
ollama serve
```

### Step 4: Configure the agent

```yaml
provider: ollama
model: qwen2:1.5b
temperature: 0.7
```

Keep the Ollama server running while using Palette.

---

## 🚀 Running Palette

### Launch the GUI

```bash
palette
```

### Run using a YAML configuration

```bash
python -m palettle.cli --config config.yaml
```

The GUI lets users configure agents, edit YAML, visualize workflows, and execute the configured task.

---

## 📁 Project Structure

```text
palette/
│
├── frontend/
│   ├── __init__.py
│   └── app.py
│
├── palettle/
│   ├── __init__.py
│   ├── cli.py
│   ├── runner.py
│   ├── config.py
│   ├── model.py
│   ├── api_key.py
│   ├── agent_builder.py
│   ├── graph_builder.py
│   ├── layer_validaor.py
│   └── error.py
│
├── main.py
├── pyproject.toml
├── README.md
└── LICENSE
```

---

## 🧩 Error Handling

Palette provides readable error messages for common issues, including:

- Missing or invalid API keys.
- Unsupported LLM providers.
- Ollama server connection failures.
- Missing Ollama models.
- API quota and rate-limit errors.
- Invalid layer configurations.

---

## 🔮 Future Improvements

- More LLM provider integrations.
- Advanced agent communication strategies.
- Parallel and conditional execution.
- Agent memory and context management.
- Workflow templates.
- More advanced graph visualization.
- Plugin-based agent extensions.

---

## 🤝 Contributing

Contributions, suggestions, and bug reports are welcome!

1. Fork the repository.
2. Create a new branch.
3. Make your changes.
4. Submit a pull request.

---

## 📄 License

This project is licensed under the MIT License. See the `LICENSE` file for details.

---

## 👩‍💻 Author

**Sejal Raykhere**

GitHub: https://github.com/sejal04-hash

---

⭐ If you find Palette useful, consider giving the repository a star!
