# Cognitive Agent Orchestrator

A modular framework for building and orchestrating autonomous AI agents with persistent memory and tool use.

## What This Project Is

This is a research-grade framework designed to coordinate multiple Large Language Model (LLM) agents to solve complex tasks. It provides structured memory (SQLite), safe tool execution, and an extensible architecture for experimenting with agent interactions.

## What This Project Is NOT

- This is **NOT** Artificial General Intelligence (AGI) or Artificial Superintelligence (ASI).
- This is **NOT** a medical device and provides **NO** medical advice.
- This is **NOT** a conscious entity. It is a software system governed by code and probability.

## Core Features

1. **Multi-Agent Orchestration**: Coordinate specialized agents (Planner, Researcher, Critic).
2. **Persistent Memory**: Local SQLite storage for interaction history and knowledge retrieval.
3. **Tool Execution**: Sandbox-ready tool execution with human-in-the-loop approval hooks.
4. **Provider Agnostic**: Supports OpenAI, Anthropic, and Groq via a unified interface.
5. **Context Awareness**: Heuristic tracking of time, entities, and conversation history.

## Architecture Overview

- **`core/orchestrator.py`**: Handles API communication with LLM providers.
- **`core/agent.py`**: Defines `Agent` behaviors and the `MultiAgentSystem` workflow.
- **`core/memory.py`**: Manages data persistence using SQLite.
- **`core/tools.py`**: Executes external tools (file I/O, Python eval).
- **`interfaces/cli.py`**: Command-line interface for interaction.

## Intended Use Cases

- Prototyping advanced agent workflows.
- Research into multi-agent collaboration patterns.
- Building internal automation tools requiring long-term memory.

## Limitations

- Performance depends entirely on the underlying LLM provider.
- The "reasoning" is a prompted simulation, not an inherent cognitive process.
- Tool execution is limited to file I/O and safe Python evaluation by default.

## Installation

### Prerequisites

- Python 3.10+
- API Key for OpenAI, Anthropic, or Groq.

### Setup

1. Clone the repository.
2. Install dependencies (using standard requirements, primarily `aiohttp`):

    ```bash
    pip install aiohttp
    ```

3. Set environment variables:

    ```bash
    export OPENAI_API_KEY="sk-..."
    # or
    export ANTHROPIC_API_KEY="sk-ant-..."
    ```

## Example Usage

Run the interactive CLI:

```bash
python -m cognitive_agent_orchestrator.interfaces.cli --interactive
```

Or process a single query:

```bash
python -m cognitive_agent_orchestrator.interfaces.cli -q "Plan a 3-day trip to Tokyo"
```

## Disclaimer

This software is for research and educational purposes only. It is provided "as is" without warranty of any kind. The authors are not responsible for any output generated by the underlying LLMs.
