docs: Update README.md with user-provided content

google-labs-jules[bot] · google-labs-jules[bot] · commit 7c2e1716d597 · 2025-09-06T20:13:29.000Z
This commit updates the README.md file with the new, more detailed content provided by the user. The new version includes badges, a roadmap, and more comprehensive setup instructions.
diff --git a/README.md b/README.md
@@ -1,108 +1,202 @@
-# Natural Language to Robot Framework
+# Mark 1 - Natural Language to Robot Framework
 
-This project is a sophisticated, AI-driven framework that translates natural language test cases into executable Robot Framework code. It leverages a multi-agent system to interpret, plan, validate, and self-correct test automation scripts, providing a seamless experience for testers and developers.
+![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
+![Python](https://img.shields.io/badge/Python-3.9%2B-green.svg)
+![Robot Framework](https://img.shields.io/badge/Robot%20Framework-6.0%2B-orange.svg)
+![Docker](https://img.shields.io/badge/Docker-Required-blue.svg)
 
----
+Transform natural language test descriptions into executable Robot Framework code using advanced AI agents. Mark 1 is an intelligent test automation platform that bridges the gap between human language and automated testing.
 
-## Key Features
+## ✨ Key Features
 
--   **Natural Language Conversion:** Simply describe a test case in plain English, and Mark 1 will generate the corresponding Robot Framework script.
--   **Multi-Agent System:** Utilizes a robust pipeline of specialized AI agents (Planner, Identifier, Validator) to ensure high-quality code generation.
--   **Self-Correction Loop:** If the generated code is syntactically incorrect, the system automatically attempts to fix its own mistakes, significantly improving reliability.
--   **Containerized Execution:** Tests are executed in a clean, isolated Docker container, guaranteeing consistency and eliminating the "it works on my machine" problem.
--   **Flexible Model Support:** Seamlessly switch between local LLMs (via Ollama) and powerful online models like Google's Gemini for maximum flexibility.
--   **Detailed Debugging:** Automatically saves detailed HTML logs and reports from every test run, allowing for easy inspection and debugging of test failures.
+- 🤖 **Multi-Agent AI System**: Sophisticated pipeline with specialized agents for planning, identification, validation, and self-correction
+- 🔄 **Self-Healing Tests**: Automatic error detection and correction through intelligent validation loops
+- 🐳 **Containerized Execution**: Clean, isolated test runs in Docker containers for consistent results
+- 🌐 **Flexible Model Support**: Works with both local LLMs (via Ollama) and cloud models (Google Gemini)
+- 📊 **Detailed Reporting**: Comprehensive HTML logs and reports for easy debugging
+- ⚡ **Real-time Streaming**: Live progress updates and instant feedback
+- 🎯 **Smart Element Detection**: AI-powered web element locator generation
 
----
+## 🏗️ Architecture
 
-## Architecture Overview
+Mark 1 employs a sophisticated multi-agent workflow:
 
-Mark 1 employs a sophisticated multi-agent workflow to ensure the generated code is both accurate and robust.
+1. **Step Planner Agent** - Decomposes natural language into structured test plans
+2. **Element Identifier Agent** - Generates optimal web element locators
+3. **Code Assembler Agent** - Creates syntactically correct Robot Framework code
+4. **Validator Agent** - Ensures code quality and correctness
+5. **Self-Correction Orchestrator** - Automatically fixes validation errors
 
-1.  **Step Planner Agent:** The initial agent receives the natural language query. Its job is to decompose the query into a high-level, structured plan, identifying each distinct action required for the test case.
-2.  **Element Identifier Agent:** This agent takes the plan and, for each step involving a UI element, uses an AI model to determine the best and most stable web locator (e.g., CSS selector, XPath).
-3.  **Code Assembler Agent:** A deterministic agent that assembles the planned and located steps into a syntactically-structured `.robot` file.
-4.  **Validator Agent:** Before execution, this crucial agent inspects the generated code against a set of rules (e.g., ensuring keywords have the correct arguments).
-5.  **Self-Correction Orchestrator:** If the Validator Agent finds a flaw, the orchestrator feeds the error back to the Step Planner Agent, which then attempts to generate a corrected plan. This loop can run multiple times to resolve errors automatically.
+## 🚀 Quick Start
 
----
+### Prerequisites
 
-## Getting Started
+- **Python 3.9+** - [Download Python](https://python.org/downloads/)
+- **Docker** - [Install Docker](https://docs.docker.com/get-docker/)
+- **Git** - [Install Git](https://git-scm.com/downloads)
+- **(Optional) Ollama** - For local AI models [Install Ollama](https://ollama.com/)
+
+### Installation
+
+1. **Clone the repository**
+   ```bash
+   git clone <repository-url>
+   cd natural-language-robot-framework
+   ```
+
+2. **Configure your AI model**
+   ```bash
+   cp backend/.env.example backend/.env
+   ```
+
+   **For Google Gemini (Recommended)**:
+   ```env
+   MODEL_PROVIDER=online
+   GEMINI_API_KEY="your-gemini-api-key-here"
+   ONLINE_MODEL=gemini-1.5-pro-latest
+   ```
 
-### Prerequisites
+   **For Local Models (Ollama)**:
+   ```env
+   MODEL_PROVIDER=local
+   LOCAL_MODEL=llama3
+   ```
 
--   **Docker:** Required for running the containerized test execution environment. [Install Docker](https://docs.docker.com/get-docker/).
--   **Python 3.9+**
--   **(Optional) Ollama:** If you wish to use a local LLM, you must have Ollama installed and running. [Install Ollama](https://ollama.com/).
-
-### Installation & Setup
-
-1.  **Clone the Repository**
-    ```bash
-    git clone <repository-url>
-    cd <repository-directory>
-    ```
-
-2.  **Configure Environment Variables**
-    Copy the example `.env` file:
-    ```bash
-    cp backend/.env.example backend/.env
-    ```
-    Now, edit `backend/.env` to configure your desired model provider.
-
-    **For Local Models (via Ollama):**
-    ```dotenv
-    MODEL_PROVIDER=local
-    LOCAL_MODEL=llama3 # The name of the model you have pulled with Ollama
-    ```
-
-    **For Online Models (Google Gemini):**
-    ```dotenv
-    MODEL_PROVIDER=online
-    GEMINI_API_KEY="YOUR_GEMINI_API_KEY"
-    # ONLINE_MODEL=gemini-1.5-pro-latest # (Optional) Specify a different Gemini model
-    ```
-
-3.  **Make Scripts Executable** (for Linux/macOS)
-    ```bash
-    chmod +x run.sh test.sh
-    ```
-
-### Running the Application
-
-1.  **Start the Server**
-    ```bash
-    ./run.sh
-    ```
-    This script automatically creates a Python virtual environment, installs all dependencies, and starts the FastAPI server on `http://localhost:5000`.
-
-2.  **Access the Web Interface**
-    Open your browser and navigate to `http://localhost:5000`.
+3. **Start the application**
+   ```bash
+   # Linux/macOS
+   chmod +x run.sh
+   ./run.sh
 
----
+   # Windows (Git Bash)
+   bash run.sh
+   ```
 
-## Usage
+4. **Access the web interface**
+   Open your browser to `http://localhost:5000`
 
-1.  Enter your test case in plain English in the text area (e.g., "search for the latest news on google and verify the title").
-2.  Click "Generate and Run".
-3.  The backend will process the query, generate the Robot Framework code, and execute it in a Docker container.
-4.  The results, including the generated code and execution logs, will be displayed on the page.
+## 💡 Usage Examples
 
-### Debugging Failed Tests
+Simply describe your test in natural language:
 
-If a test fails, you can find detailed information in the `robot_tests` directory. The framework automatically saves the following files from the container to your local machine:
--   `log.html`: A detailed, step-by-step log of the test execution with expandable views.
--   `report.html`: A high-level report of the test run.
--   `output.xml`: The machine-readable XML output from Robot Framework.
+### Basic Examples
+- *"Open Google, search for 'Robot Framework tutorials', and click the first result"*
+- *"Navigate to GitHub, search for 'selenium automation', and star the top repository"*
+- *"Go to YouTube, search for 'Python automation', and play the first video"*
 
-Simply open `log.html` in your browser to get a complete picture of the failure.
+### Advanced Examples
+- *"Visit Amazon, search for 'wireless headphones', filter by rating above 4 stars, and add the top result to cart"*
+- *"Open LinkedIn, search for 'QA Engineer' jobs in San Francisco, and apply filters for remote work"*
+- *"Navigate to Stack Overflow, search for 'pytest fixtures', and upvote the most helpful answer"*
 
----
+## 🛠️ Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `MODEL_PROVIDER` | AI model provider (`online` or `local`) | `online` |
+| `GEMINI_API_KEY` | Google Gemini API key | Required for online |
+| `ONLINE_MODEL` | Gemini model name | `gemini-1.5-pro-latest` |
+| `LOCAL_MODEL` | Ollama model name | `llama3` |
+| `SECONDS_BETWEEN_API_CALLS` | Rate limiting delay | `0` |
+
+### Getting API Keys
+
+**Google Gemini API Key**:
+1. Visit [Google AI Studio](https://aistudio.google.com/app/apikey)
+2. Create a new API key
+3. Copy the key to your `.env` file
+
+## 🧪 Testing
+
+Test the API endpoint directly:
+
+```bash
+chmod +x test.sh
+./test.sh
+```
+
+Or use curl:
+
+```bash
+curl -X POST \
+  -H "Content-Type: application/json" \
+  -d '{"query": "go to google.com and search for python tutorials", "model": "gemini-1.5-pro-latest"}' \
+  http://localhost:5000/generate-and-run
+```
+
+## 📁 Project Structure
 
-## License
+```
+├── backend/
+│   ├── main.py              # FastAPI application
+│   ├── robot_generator.py   # Multi-agent AI system
+│   ├── requirements.txt     # Python dependencies
+│   └── .env                # Configuration
+├── frontend/
+│   ├── index.html          # Web interface
+│   ├── script.js           # Frontend logic
+│   └── style.css           # Styling
+├── robot_tests/            # Generated test files and reports
+├── run.sh                  # Startup script
+└── test.sh                 # Testing script
+```
 
-This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.
+## 🐛 Debugging
 
-## Contributing
+When tests fail, detailed logs are automatically saved:
+
+- `robot_tests/{run_id}/log.html` - Step-by-step execution log
+- `robot_tests/{run_id}/report.html` - High-level test report
+- `robot_tests/{run_id}/output.xml` - Machine-readable results
+
+Open `log.html` in your browser for comprehensive failure analysis.
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+
+1. Fork the repository
+2. Create a feature branch: `git checkout -b feature/amazing-feature`
+3. Make your changes
+4. Run tests: `./test.sh`
+5. Commit: `git commit -m 'Add amazing feature'`
+6. Push: `git push origin feature/amazing-feature`
+7. Open a Pull Request
+
+Before contributing, please read our [Contributor License Agreement](CLA.md).
+
+## 📄 License
+
+This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
+
+## 🆘 Support
+
+- 📚 **Documentation**: Check this README and code comments
+- 🐛 **Issues**: Report bugs via GitHub Issues
+- 💬 **Discussions**: Join our GitHub Discussions
+- 📧 **Email**: Contact the maintainers
+
+## 🎯 Roadmap
+
+- [ ] Support for mobile app testing
+- [ ] Integration with CI/CD pipelines
+- [ ] Visual test result dashboards
+- [ ] Multi-language test generation
+- [ ] Advanced AI model fine-tuning
+- [ ] Cloud deployment options
+
+## ⭐ Show Your Support
+
+If Mark 1 helps streamline your testing workflow, please consider:
+- ⭐ Starring this repository
+- 🐛 Reporting issues
+- 💡 Suggesting new features
+- 🤝 Contributing code
+
+---
 
-We welcome contributions to this project! Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for details on how to get started and to review our contributor license agreement.
+**Built with ❤️ for the test automation community**
