--- description: Apply these rules when creating the project globs: alwaysApply: true --- ## Project Overview * **Type:** cursor_project_rules * **Description:** OWL (Optimized Workforce Learning for General Multi-Agent Assistance) is a cutting-edge multi-agent collaboration framework built on top of the CAMEL-AI framework. It focuses on dynamic agent interactions to solve complex, real-world tasks by leveraging toolkits and multiple LLM backends to automate processes efficiently. * **Primary Goal:** Create a robust multi-agent system capable of solving complex, real-world tasks through dynamic collaboration, extensibility, and seamless integration with various toolkits and LLM backends. ## Project Structure ### Framework-Specific Routing * **Directory Rules:** * **[gradio@latest]:** Routes are managed via a Gradio-based web interface. The primary entry point is a single-file or modularized layout (e.g., `ui/app.py`) that defines the interactive components and backend calls. * Example: For a Python project using Gradio, routing is handled within the application code rather than through a dedicated folder structure like Next.js routers. ### Core Directories * **Versioned Structure:** * `owl/agents`**:** Contains implementations for multi-agent roles including user and assistant agents, ensuring version-specific logic and interactions as per CAMEL-AI framework. * `owl/toolkits`**:** Holds integration logic for various toolkits (Web, Document Processing, Code Execution, etc.) that agents utilize during task execution. * `owl/ui`**:** Consists of the Gradio-based web interface files, configuration scripts, and components facilitating user interaction. * `docker`**:** Contains Dockerfiles and related scripts to ensure cross-platform (macOS/Linux, Windows) consistency in deployments. ### Key Files * **Stack-Versioned Patterns:** * `main.py`**:** The primary entry point that initializes the agent society, orchestrates tool integration, and manages the overall workflow. * `owl/agents/agent.py`**:** Implements the core functionalities for both user and assistant agents based on CAMEL-AI standards. * `owl/ui/app.py`**:** Establishes the web interface using Gradio, integrating model selection, task input, and output display. * `docker/Dockerfile`**:** Contains configuration for containerized deployment ensuring environment consistency. ## Tech Stack Rules * **Version Enforcement:** * **python@3.9+:** Enforce use of type hints, modern Python practices, and adherence to PEP 8 standards. * **camel_ai@stable:** Maintain core multi-agent communication patterns without deviating from the prescribed agent roles. * **gradio@latest:** Use the latest Gradio conventions to build an interactive and responsive UI. * **docker@latest:** Ensure containerization aligns with current Docker best practices for reproducible deployments. * **Other Libraries (openai_gpt_4o, qwen, deepseek, ollama, playwright, langchain, tiktoken, selenium, beautifulsoup4, requests, pydantic, lxml, chromadb):** Use versions as specified in the tech stack document; adhere to each library’s best practices and update guidelines. ## PRD Compliance * **Non-Negotiable:** * "OWL is a cutting-edge multi-agent collaboration framework designed to automate complex real-world tasks." This mandates that all development strictly follows the dynamic agent interaction model, robust tool integration, and extensibility requirements as detailed in the PRD. ## App Flow Integration * **Stack-Aligned Flow:** * Example: "OWL Multi-Agent Flow" – The process begins with user input (via command line or web UI), followed by the construction of an agent society in `owl/agents/agent.py`. The assistant agent then selects and utilizes appropriate toolkits (located in `owl/toolkits`) to process tasks, execute code if necessary, and ultimately generate comprehensive responses. The Gradio UI (`owl/ui/app.py`) ensures that these interactions are visible and manageable by the user. ## Best Practices * **python** * Write clean, modular code with proper type annotations and adhere to PEP 8. * Utilize virtual environments to manage dependencies and isolate projects. * Implement comprehensive logging and error-handling mechanisms. * **camel_ai** * Keep agent role definitions clear and decoupled to facilitate maintenance and updates. * Regularly update and test communication protocols between agents. * Maintain thorough documentation for custom agent behaviors and toolkit integrations. * **openai_gpt_4o, qwen, deepseek, ollama** * Follow API usage best practices and ensure secure key management. * Monitor performance and adjust model parameters to optimize response times and accuracy. * Validate outputs rigorously to handle unexpected model behavior. * **gradio** * Design intuitive UI layouts that promote ease of use and quick task initiation. * Ensure responsive design and quick feedback loops for user inputs. * Keep the UI code modular to facilitate future enhancements. * **playwright** * Write robust selectors for browser automation to ensure reliability in dynamic web environments. * Implement retries and error handling for network-related issues. * Keep automation scripts separate from core logic to maintain modularity. * **langchain** * Maintain clear documentation for data connectors and custom chain implementations. * Ensure secure handling of data passing between components. * Regularly test integrations with various LLM backends. * **docker** * Build minimal and secure container images following Docker best practices. * Use multi-stage builds to optimize image size and security. * Regularly update base images to incorporate security patches. * **tiktoken, selenium, beautifulsoup4, requests, pydantic, lxml, chromadb** * Adhere to version-specific guidelines provided in the tech stack documentation. * Write unit tests to cover key functionality for each library integration. * Monitor for updates and breaking changes to maintain compatibility. ## Rules * Derive folder/file patterns directly from the tech stack documented versions and structure (e.g., `owl/agents` for agent logic, `owl/toolkits` for integrations, and `owl/ui` for the web interface). * For Python and Gradio-based projects, enforce a clear separation between business logic, agent interactions, and UI components. * Maintain consistency and do not mix version-specific patterns across different segments of the project (e.g., avoid blending modular UI components with monolithic script patterns). * Ensure that any changes follow the core guidelines defined in the PRD, respecting both non-negotiable requirements and version-specific constraints. * Regularly review and update documentation to reflect any changes in the underlying tech stack versions or architectural decisions.