Troubleshooting

Troubleshooting Guide

While Peeps AI is designed to provide a seamless experience, you may encounter issues during setup, configuration, or execution. This troubleshooting guide addresses common challenges and provides step-by-step solutions to help you resolve them efficiently.


Installation Problems

Issue: Dependency installation fails during the setup.

Possible Causes and Solutions:

Python Version Mismatch Peeps AI requires Python >=3.10 and <3.13.

  • Check your Python version:

    python --version
  • If the version is incorrect, download the correct version from Python.org and ensure it is properly added to your PATH.

Outdated pip

  • Upgrade pip to the latest version:

    python -m pip install --upgrade pip

Missing Build Tools Some dependencies require additional tools:

  • On Windows: Install Visual C++ Build Tools.

  • On Linux: Install build-essential:

    sudo apt-get install build-essential
  • On macOS: Install Xcode Command Line Tools:

    xcode-select --install

Virtual Environment Errors

Issue: Virtual environment commands fail or dependencies aren’t isolated.

Solutions:

❖ Ensure the virtual environment is activated:

  • On Unix/macOS:

    source venv/bin/activate
  • On Windows:

    venv\Scripts\activate

❖ If activation fails, recreate the virtual environment:

python -m venv venv

❖ If dependencies conflict, clear the environment and reinstall:

rm -rf venv
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

YAML Configuration Issues

Issue: Errors when loading agents.yaml or tasks.yaml.

Possible Causes and Solutions:

Syntax Errors YAML is sensitive to indentation.

  • Use a linter or online YAML validator to check for formatting issues.

  • Ensure consistent use of spaces (no tabs).

Undefined Agents or Tasks

  • Ensure all tasks reference valid agents defined in agents.yaml.

  • Example:

# tasks.yaml
research_task:
  description: "Perform analysis"
  agent: researcher

# agents.yaml
researcher:
  role: "Researcher"
  goal: "Analyze trends"

Dynamic Input Errors For tasks with placeholders like {sector}, ensure you pass the required input during execution.


Execution Errors

Issue: The project fails to run or outputs unexpected results.

Possible Causes and Solutions:

Missing Dependencies

  • Verify that all dependencies are installed:

    pip install -r requirements.txt

Environment Variables Not Set

  • Ensure the .env file contains required keys (e.g., OPENAI_API_KEY).

  • Example .env:

    OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

Task Misconfiguration

  • Check tasks.yaml for valid descriptions, outputs, and assigned agents.

Agent Behavior Issues

  • Test agent definitions in agents.yaml:

    from peepsai import load_agents
    agents = load_agents("config/agents.yaml")
    print(agents)

❖ Command Line Interface (CLI) Issues

Issue: Commands like peepsai run fail.

Solutions:

Ensure the Project Directory is Correct Navigate to your Peeps AI project directory:

cd ~/projects/my_project

Verify the Peeps AI Installation Confirm that Peeps AI is correctly installed by running:

python -m peepsai --version

If this command fails, it may indicate an issue with your project setup.

Reinstall Peeps AI If the CLI remains unresponsive, re-clone the Peeps AI repository to ensure all files are correctly downloaded and installed:

# Remove the current installation
rm -rf ~/projects/peepsai

# Re-clone the Peeps AI repository
git clone https://github.com/peepsai/peepsai.git ~/projects/peepsai
cd ~/projects/peepsai

# Reinstall dependencies
python -m pip install -r requirements.txt

By ensuring the repository is properly cloned and dependencies are installed, CLI commands like peepsai run should function as expected.


Logging and Debugging

Issue: Unclear error messages or unexpected behaviors.

Solutions:

Enable Verbose Mode Add verbose=True to your Peeps AI workflow definitions (e.g., in group.py):

Peeps(agents=agents, tasks=tasks, process=Process.sequential, verbose=True)

Check Logs Use logs to pinpoint issues:

peepsai run --log-level DEBUG

Print Intermediate Outputs Insert print statements in main.py or group.py to debug configurations.


Git-Related Issues

Issue: Unable to clone the Peeps AI repository.

Solutions:

❖ Verify Git installation:

git --version

If not installed, download it from Git-SCM.

❖ Check internet connectivity or firewall restrictions.

❖ If cloning fails due to permissions, ensure the repository URL is correct:

git clone https://github.com/peepsai/peepsai.git

Performance Issues

Issue: Tasks take too long to execute or fail to complete.

Solutions:

❖ Optimize agent definitions to reduce complexity.

❖ Use smaller datasets or limit the scope of initial tasks for testing.

❖ If using an external API (e.g., OpenAI), ensure you are within rate limits.


Frequently Encountered Errors


Getting Additional Support

If you’ve tried the above solutions and still face challenges:

  • Visit the Peeps AI GitHub Issues Page to report bugs or view existing resolutions.

  • Join the Peeps AI community forums or Slack for peer assistance.

  • Reach out to the support team (details in the documentation).

Last updated