| --- | |
| 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:** | |
| * **[email protected]+:** 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. | |