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).