{"id":22907428,"url":"https://github.com/matiascarabella/self-driving-ai","last_synced_at":"2026-05-18T09:34:41.245Z","repository":{"id":264401506,"uuid":"867859665","full_name":"MatiasCarabella/self-driving-ai","owner":"MatiasCarabella","description":"2D self-driving car simulation developed in Python using Pygame, featuring a Q-learning agent that learns to navigate a circuit.","archived":false,"fork":false,"pushed_at":"2025-11-30T20:26:13.000Z","size":412,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-12-03T05:36:37.680Z","etag":null,"topics":["2d-simulation","artificial-intelligence","computer-vision","machine-learning","pygame","python","q-learning","reinforcement-learning","self-driving-car"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MatiasCarabella.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-10-04T21:43:28.000Z","updated_at":"2025-11-30T20:26:17.000Z","dependencies_parsed_at":null,"dependency_job_id":"1cc3f8da-9397-43e2-8e7c-f1b6b3ae602e","html_url":"https://github.com/MatiasCarabella/self-driving-ai","commit_stats":null,"previous_names":["matiascarabella/self-driving-ai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MatiasCarabella/self-driving-ai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatiasCarabella%2Fself-driving-ai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatiasCarabella%2Fself-driving-ai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatiasCarabella%2Fself-driving-ai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatiasCarabella%2Fself-driving-ai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatiasCarabella","download_url":"https://codeload.github.com/MatiasCarabella/self-driving-ai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatiasCarabella%2Fself-driving-ai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33172652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-18T09:27:30.708Z","status":"ssl_error","status_checked_at":"2026-05-18T09:27:28.300Z","response_time":71,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d-simulation","artificial-intelligence","computer-vision","machine-learning","pygame","python","q-learning","reinforcement-learning","self-driving-car"],"created_at":"2024-12-14T03:15:12.193Z","updated_at":"2026-05-18T09:34:41.240Z","avatar_url":"https://github.com/MatiasCarabella.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv id=\"user-content-toc\"\u003e\n  \u003cul align=\"center\" style=\"list-style: none;\"\u003e\n    \u003csummary\u003e\n      \u003ch1\u003eSelf-Driving AI 🧬\u003c/h1\u003e\n    \u003c/summary\u003e\n  \u003c/ul\u003e\n\u003c/div\u003e\n\u003cdiv align=\"center\"\u003e\n   \u003ca href=\"https://www.python.org/\" target=\"_blank\"\u003e\u003cimg src=\"https://img.shields.io/badge/Python-3.x-3776AB?logo=python\u0026logoColor=fff\" alt=\"Python\" /\u003e\u003c/a\u003e\n\u003c/div\u003e\n\u003ch1\u003e\u003c/h1\u003e\n\nThis project is a 2D self-driving car simulation developed in Python using Pygame. It features a Q-learning agent that learns to navigate a circuit by interacting with its environment and optimizing its actions through a reward system. \n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://i.imgur.com/XMouIzG.gif\" alt=\"Self-Driving AI gif\"\u003e\n\u003c/p\u003e\n\n## Features\n- **Reinforcement Learning**: Implements Q-learning to train an AI agent to navigate a circuit.\n- **Sensor System**: The vehicle is equipped with sensors that provide information about its surroundings, allowing for informed decision-making.\n- **Visual Feedback**: Real-time visualization of the vehicle's performance, including speed, scores, and sensor values.\n- **Logging**: Tracks the performance of the agent across episodes and stores it for further analysis.\n- **Dual Mode Operation**: Supports both training and simulation modes through the LEARNING_MODE configuration.\n\n## Setup Instructions\n\n### Prerequisites\nTo run this project, you'll need Python 3.x along with the required libraries. You can install them using pip:\n```bash\npip install -r requirements.txt\n```\n### Installation\n\n1. Clone the repository:\n```bash\ngit clone https://github.com/matiascarabella/self-driving-ai.git\ncd self-driving-ai\n```\n\n## Usage\n\n### Standard Training (with visualization)\n```bash\npython main.py\n```\n\n### Fast Training (headless mode - 5-10x faster)\n```bash\npython train_fast.py\n```\nRuns without rendering for much faster training. Perfect for overnight training sessions.\n\n### Command Line Options\nOverride config settings from the command line:\n```bash\npython main.py --circuit circuit_1 --episodes 100 --headless\npython main.py --eval                    # Evaluation mode (no training)\npython main.py --manual                  # Manual control with arrow keys\n```\n\n### Watch Trained Agent (Evaluation Mode)\n```bash\npython watch_agent.py\n```\nWatch your trained agent perform without any learning or logging. The agent uses its learned knowledge deterministically.\n\n## Improving Agent Performance\n\nIf your agent gets stuck or isn't learning well:\n\n1. **Increase exploration**: Lower `MIN_EXPLORATION_RATE` in config.py\n2. **Train longer**: Use `--episodes 10000` or more\n3. **Try different circuits**: Each circuit teaches different skills\n4. **Adjust rewards**: Tune `REWARD_CONFIG` values in config.py\n\n## Project Structure\n```\nself-driving-ai/\n├── assets/\n│   └── images/\n│       ├── circuit_1.png          # Horizontal circuit (1893x493)\n│       └── circuit_2.png          # Square circuit (801x601)\n├── logs/\n│   ├── q_learning/\n│   │   ├── circuit1_v1.txt        # Episode scores for circuit 1\n│   │   ├── circuit1_v1_metrics.json\n│   │   ├── circuit2_v1.txt        # Episode scores for circuit 2\n│   │   └── circuit2_v1_metrics.json\n│   └── logger.py                  # Logging utilities\n├── machine_learning/\n│   └── q_learning/\n│       ├── q_tables/\n│       │   ├── circuit1_v1.pkl    # Learned Q-table for circuit 1\n│       │   └── circuit2_v1.pkl    # Learned Q-table for circuit 2\n│       └── agent.py               # Q-learning agent implementation\n├── models/\n│   ├── checkpoint.py              # Checkpoint detection system\n│   ├── environment.py             # Game environment and rendering\n│   ├── sensor.py                  # Vehicle sensor system\n│   └── vehicle.py                 # Vehicle physics and state\n├── visualization/\n│   └── plot_training.py           # Training progress visualization\n├── .gitignore\n├── config.py                      # All configuration parameters\n├── LICENSE\n├── main.py                        # Main entry point with CLI support\n├── README.md\n├── requirements.txt               # Python dependencies (pinned versions)\n├── train_fast.py                  # Headless training wrapper\n└── watch_agent.py                 # Evaluation mode wrapper\n```\n\n## Configuration\nThe project includes a `config.py` file where you can adjust various parameters:\n\n### Session Configuration\n```python\nSESSION_CONFIG = {\n    \"TRAINING_MODE\": True,    # Toggle between training and evaluation modes\n    \"NUM_EPISODES\": 50,       # Number of episodes to run\n    \"EPISODE_DURATION\": 20,   # Duration of each episode in seconds\n    \"MANUAL_CONTROL\": False,  # Enable manual control with arrow keys\n    \"HEADLESS\": False,        # Run without rendering (5-10x faster)\n    \"FRAME_SKIP\": 1,          # Render every Nth frame (higher = faster)\n    \"CIRCUIT\": \"circuit_2\"    # Which circuit to use: \"circuit_1\" or \"circuit_2\"\n}\n```\n\n### Circuit Configuration\n```python\nCIRCUIT_CONFIG = {\n    \"circuit_1\": {\n        \"window_size\": (1200, 400),\n        \"start_angle\": 0,      # Point right\n        \"q_table\": \"circuit1_v1.pkl\"\n    },\n    \"circuit_2\": {\n        \"window_size\": (800, 600),\n        \"start_angle\": 180,    # Point left\n        \"q_table\": \"circuit2_v1.pkl\"\n    }\n}\n```\n\n#### Agent Modes\n- **Training Mode** (`TRAINING_MODE = True`):\n  - Used for training the agent\n  - Agent explores new actions using epsilon-greedy strategy\n  - Updates Q-table based on experiences\n  - Behavior varies between runs due to exploration\n\n- **Evaluation Mode** (`TRAINING_MODE = False`):\n  - Used for testing or demonstrating learned behavior\n  - Agent uses learned knowledge deterministically\n  - No Q-table updates or exploration\n  - Consistent behavior between runs\n\n### Other Configuration Options\n- Vehicle settings (dimensions, speed, acceleration)\n- Q-learning parameters (learning rate, discount factor, exploration rate)\n- Window and display settings\n\n## Log Files\nThe training results are logged within the `logs/q_learning/` folder:\n- `circuit1_v1.txt` / `circuit2_v1.txt`: Records the final score for each episode\n- `circuit1_v1_metrics.json` / `circuit2_v1_metrics.json`: Detailed metrics including:\n  - Episode number\n  - Score and distance traveled\n  - Exploration rate (epsilon)\n  - Collision status\n  - Finish line reached\n\nThese logs can be used for performance analysis and progress visualization. Each circuit maintains separate logs.\n\n## Visualizing Progress\nVisualize your agent's training progress:\n\n```bash\npython visualization/plot_training.py\n```\n\nShows distance traveled over episodes - the primary metric for learning progress. The visualization:\n- Displays raw distance data with moving average\n- Shows max distance achieved with reference line\n- Marks new records with star (★) indicators\n- Includes key statistics (episodes, peak, avg last 100)\n- Automatically merges multiple training sessions into a continuous timeline\n\nThe plot automatically uses the metrics file for the current circuit in config.py.\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://github.com/user-attachments/assets/f8bc373f-3271-44d0-b3a3-5409cae49b68\" /\u003e\n\u003c/p\u003e\n\n## License\nThis project is licensed under the [MIT License](LICENSE).\n\n## Acknowledgments\n- OpenAI for inspiring the use of AI and reinforcement learning concepts.\n- Pygame for the graphics library used in this project.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiascarabella%2Fself-driving-ai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatiascarabella%2Fself-driving-ai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatiascarabella%2Fself-driving-ai/lists"}