Multi-Agent AI System for Input Processing

1. Project Overview

This project implements a multi-agent AI system designed to accept input in various formats (JSON file, Email text/file, potentially PDF), classify the input format and intent, and route it to the appropriate specialized agent for processing. The system utilizes a shared memory module to maintain context and traceability across agents for each processed input.

The primary goal is to create a modular and extensible framework for handling different types of incoming data streams, extracting relevant information, and preparing it for downstream use (e.g., CRM systems, databases).

2. Architecture

The system consists of the following core components:

• Orchestrator (main.py): The central control unit that receives input, initiates the classification process, and routes the task to the appropriate agent based on the classifier's output.
• Shared Memory (shared_memory/memory.py): A thread-safe, in-memory dictionary acting as a lightweight database. It stores context for each processing thread (input), including source details, classification results, extracted data, status updates, and logs.
• Classifier Agent (agents/classifier_agent.py): Responsible for:
  • Detecting the format of the input (JSON, Email, PDF, Text File).
  • Performing basic intent classification (using placeholder logic currently; designed for LLM integration).
  • Creating a new thread entry in the Shared Memory.
  • Logging classification results to the Shared Memory.
• JSON Agent (agents/json_agent.py): Processes inputs classified as JSON. It:
  • Loads JSON data (from file or memory).
  • Validates the data against a predefined target schema.
  • Extracts data according to the schema.
  • Flags anomalies (missing required fields, type mismatches).
  • Updates the Shared Memory with extracted data and processing status.
• Email Agent (agents/email_agent.py): Processes inputs classified as Email. It:
  • Parses raw email content using Python's email library to extract headers (From, To, Subject) and body.
  • Determines urgency (using placeholder logic currently; designed for LLM integration).
  • Formats extracted information into a CRM-style structure.
  • Updates the Shared Memory with the formatted data and processing status.
• Utilities (utils/): Placeholder for helper functions (currently empty).
• Tests (tests/): Placeholder for automated tests (currently contains sample input files used for manual testing).

3. Folder Structure

multi_agent_system/
├── agents/
│   ├── __init__.py
│   ├── classifier_agent.py
│   ├── email_agent.py
│   └── json_agent.py
├── shared_memory/
│   ├── __init__.py
│   └── memory.py
├── tests/
│   └── __init__.py
│   # (Contains test files like test_invoice.json, test_email.txt)
├── utils/
│   └── __init__.py
│   └── helpers.py
├── main.py             # Main orchestrator script
├── requirements.txt    # Dependencies (currently minimal)
├── README.md           # This file
└── todo.md             # Development checklist (internal)

4. Setup

1. Prerequisites:
   • Python 3.x (developed with 3.11)
   • (Optional, for PDF processing if implemented) poppler-utils: Install via your system's package manager (e.g., sudo apt-get update && sudo apt-get install poppler-utils on Debian/Ubuntu, brew install poppler on macOS).
2. Dependencies: Currently, the core system uses only standard Python libraries. If you integrate an LLM (like Google Generative AI), install the required library:

   pip install -r requirements.txt
   # Add 'google-generativeai' or other libraries to requirements.txt first

5. Usage

Run the system from the command line using the main.py script, providing the input source as an argument.

• Processing a JSON file:

  python main.py /path/to/your/invoice.json

  (Example using the test file provided)

  python main.py test_invoice.json

• Processing an Email file: (Note: The current classifier identifies .txt files containing email content as text_file, not email. You might need to adjust the classifier or pass raw content.)

  python main.py /path/to/your/email.txt

  (Example using the test file provided - will be classified as text_file)

  python main.py test_email.txt

• Processing Raw Email Text:

  python main.py "From: user@example.com\nTo: support@example.com\nSubject: Urgent Complaint\n\nMy device is broken!"

  (The orchestrator detects this is not a file path and passes the raw string.)

• Processing a PDF file (Detection Only): (Requires a dummy PDF file, e.g., touch dummy.pdf)

  python main.py dummy.pdf

  (The system will classify it as PDF but state that processing is not implemented.)

The script will print logs to the console showing the classification, routing, and agent processing steps.

6. LLM Integration (Placeholder)

The system is designed for integration with a Large Language Model (LLM) like Google Generative AI via the Google Studio API key for more advanced intent classification and urgency detection.

• API Key: You need to replace the placeholder "YOUR_GOOGLE_STUDIO_API_KEY" in agents/classifier_agent.py and potentially agents/email_agent.py with your actual API key.
• Client Initialization: Uncomment and configure the LLM client initialization lines in the respective agent files.
• API Calls: Uncomment and adapt the placeholder LLM API call sections within the _classify_intent and _determine_urgency methods.
• Dependencies: Add the necessary LLM library (e.g., google-generativeai) to requirements.txt and install it.

7. PDF Handling

• Detection: The ClassifierAgent can detect files with a .pdf extension.
• Extraction: Text extraction from PDFs is not implemented in this version. The ClassifierAgent contains commented-out placeholder code using the pdftotext command-line utility (requires poppler-utils).
• Routing: Inputs classified as PDF are currently routed to a placeholder message indicating that processing is not implemented.

8. Limitations & Next Steps

• Placeholder Logic: Intent classification and email urgency detection currently use simple keyword matching. Full implementation requires integrating an LLM.
• PDF Processing: PDF text extraction and subsequent processing logic need to be implemented (e.g., creating a dedicated PDFAgent).
• Email Classification: The file-based classifier currently identifies the .txt email sample as text_file. The classifier logic could be enhanced to inspect file content more deeply or rely on raw text input for emails.
• Text File Handling: Generic text file processing is not implemented.
• Error Handling: Error handling is basic; more robust error logging and recovery mechanisms could be added.
• Schema Management: The JSON schema in JSONAgent is hardcoded; it could be loaded from a configuration file.
• Configuration: API keys and other settings could be managed via environment variables or a dedicated configuration file.
• Testing: Only basic manual tests were performed. Comprehensive unit and integration tests should be added in the tests/ directory.
• Shared Memory Persistence: The current shared memory is in-memory only and data is lost when the script ends. For persistence, replace it with Redis, SQLite, or another database solution.

9. Test Results Summary

Manual tests were run using test_invoice.json and test_email.txt:

• JSON Input (test_invoice.json): Successfully classified as json format and Invoice intent. Routed to JSONAgent, which processed the data against the schema without anomalies.
• Email Input (test_email.txt): Classified as text_file format and Complaint intent (based on keywords). Routed to the placeholder for generic text handling, as the classifier didn't identify it specifically as email based on the file extension and content check used.
• Raw Email Text (Manual Test): Successfully classified as email format and routed to EmailAgent for processing.
• PDF Input (Dummy File): Successfully classified as pdf format, routing indicated processing not implemented.