{"id":29620553,"url":"https://github.com/lukehollis/three-mlagents","last_synced_at":"2025-10-16T17:49:01.585Z","repository":{"id":301911092,"uuid":"1010648306","full_name":"lukehollis/three-mlagents","owner":"lukehollis","description":"Three.js + Torch implementation of Unity's ML-Agents framework for agent training and visualization in browser","archived":false,"fork":false,"pushed_at":"2025-10-04T22:22:55.000Z","size":41234,"stargazers_count":23,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T23:28:40.891Z","etag":null,"topics":["deep-learning","deep-reinforcement-learning","machine-learning","neural-networks","reinforcement-learning","three-js","threejs","torch"],"latest_commit_sha":null,"homepage":"https://lukehollis.github.io/three-mlagents/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukehollis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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":"2025-06-29T14:20:30.000Z","updated_at":"2025-10-04T22:22:58.000Z","dependencies_parsed_at":"2025-06-29T15:31:42.603Z","dependency_job_id":"dd6f352d-6a70-484a-a30c-64b330b36394","html_url":"https://github.com/lukehollis/three-mlagents","commit_stats":null,"previous_names":["lukehollis/three-mlagents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lukehollis/three-mlagents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukehollis%2Fthree-mlagents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukehollis%2Fthree-mlagents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukehollis%2Fthree-mlagents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukehollis%2Fthree-mlagents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukehollis","download_url":"https://codeload.github.com/lukehollis/three-mlagents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukehollis%2Fthree-mlagents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279221055,"owners_count":26128889,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["deep-learning","deep-reinforcement-learning","machine-learning","neural-networks","reinforcement-learning","three-js","threejs","torch"],"created_at":"2025-07-21T03:35:34.850Z","updated_at":"2025-10-16T17:49:01.532Z","avatar_url":"https://github.com/lukehollis.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Three ML-Agents\n\n[![Live demo](https://img.shields.io/badge/web-live%20demo-brightgreen?style=flat\u0026logo=github)](https://lukehollis.github.io/three-mlagents/)\n![GitHub stars](https://img.shields.io/github/stars/lukehollis/three-mlagents?style=flat\u0026logo=github)\n![GitHub last commit](https://img.shields.io/github/last-commit/lukehollis/three-mlagents?style=flat\u0026logo=github)\n[![License](https://img.shields.io/badge/license-MIT-blue.svg?style=flat)](#license)\n\n![React](https://img.shields.io/badge/React-18+-61dafb?style=flat\u0026logo=react)\n![Three.js](https://img.shields.io/badge/Three.js-r150+-000000?style=flat\u0026logo=three.js)\n![Python](https://img.shields.io/badge/Python-3.9+-3776ab?style=flat\u0026logo=python)\n![FastAPI](https://img.shields.io/badge/FastAPI-latest-009688?style=flat\u0026logo=fastapi)\n\nA **JavaScript / Python** re-implementation of the core [Unity ML-Agents](https://github.com/Unity-Technologies/ml-agents) examples. Test out the [Live Demos](https://lukehollis.github.io/three-mlagents/).\n\n![threejs_mlagents_overview](https://github.com/user-attachments/assets/933f8214-552d-4241-a726-f40ce4d765ff)\n\n\n\nThe goal of this repository is to make the ideas from Unity ML-Agents easily approachable from the browser (React + Three.js) and from lightweight Python back-ends (FastAPI) to be used for future study.\n\n\n\n## Examples\n\nView all the demos on the live demos page: [Live Demos](https://lukehollis.github.io/three-mlagents/). \n\nSelect demos are here. \n\n\n### MineCraft\n\n![minecraft_example](https://github.com/user-attachments/assets/1338e926-8c8d-412e-bc2c-0627e47df165)\n\n\n[Live demo](https://lukehollis.github.io/three-mlagents/minecraft)\n\n### Glider\n\n![glider_example](https://github.com/user-attachments/assets/1c82281a-6982-4d05-95e4-816e6b8f61b4)\n\n\n[Live demo](https://lukehollis.github.io/three-mlagents/glider)\n\n### Astrodynamics\n\n![astrodynamics_example](https://github.com/user-attachments/assets/d06b7d03-1ade-409f-aabc-fb1b283c7aab)\n\n[Live demo](https://lukehollis.github.io/three-mlagents/astrodynamics)\n\n### Fish\n\n![fish_example](https://github.com/user-attachments/assets/2b45d7c0-7eac-4cc1-a383-9a92740d78e1)\n\n[Live demo](https://lukehollis.github.io/three-mlagents/fish)\n\n\n### Self-driving Car (Interpretability)\n\n![self_driving_car_interpretability_example](https://github.com/user-attachments/assets/7bf64b31-71fa-4c3b-a872-9aa952df4285)\n\n\n[Live demo](https://lukehollis.github.io/three-mlagents/self-driving-car)\n\n\n### Labyrinth\n\n![labyrinth_example](https://github.com/user-attachments/assets/39a2fe92-d279-4d23-a816-9c2a76e538b6)\n\n[Live demo](https://lukehollis.github.io/three-mlagents/labyrinth)\n\n\n| Demo                           | Live Demo                                                          |\n|--------------------------------|--------------------------------------------------------------------|\n| Basic 1-D Move to Goal         | [Live Demo](https://lukehollis.github.io/three-mlagents/basic)     |\n| 3DBall Balance                 | [Live Demo](https://lukehollis.github.io/three-mlagents/ball3d)    |\n| GridWorld Navigation           | [Live Demo](https://lukehollis.github.io/three-mlagents/gridworld) |\n| Push-Block                     | [Live Demo](https://lukehollis.github.io/three-mlagents/push)      |\n| Wall Jump                      | [Live Demo](https://lukehollis.github.io/three-mlagents/walljump)  |\n| Ant (Crawler)                  | [Live Demo](https://lukehollis.github.io/three-mlagents/crawler)   |\n| Swimmer / Worm                 | [Live Demo](https://lukehollis.github.io/three-mlagents/worm)      |\n| Brick Break                    | [Live Demo](https://lukehollis.github.io/three-mlagents/brickbreak)|\n| Food Collector                 | [Live Demo](https://lukehollis.github.io/three-mlagents/foodcollector) |\n| Bicycle                        | [Live Demo](https://lukehollis.github.io/three-mlagents/bicycle)   |\n| Intersection                   | [Live Demo](https://lukehollis.github.io/three-mlagents/intersection) |\n\n## Project layout\n\n```\nthree-mlagents/\n│\n├─ client/         ← Vite + React + Three.js front-end (examples live here)\n│   └─ src/examples\n│       ├─ Index.jsx  ← landing page listing all examples\n│       └─ Basic.jsx  ← 1-D \"move-to-goal\" environment matching Unity Basic\n│\n├─ api/            ← FastAPI micro-service (Python ≥3.9)\n│   ├─ main.py      ← gym-style REST API for each environment\n│   └─ requirements.txt\n│\n└─ ml-agents/      ← Upstream Unity project kept for reference only (no build step)\n```\n\nYou only need **client** and **api** to run the demos. The `ml-agents` directory remains untouched so you can cross-reference the original C#/Unity code (see `Examples/Basic/Scripts/BasicController.cs` for this particular demo).\n\n---\n\n## Quick start\n\n### 1. Front-end (browser)\n\n```bash\ncd client\nnpm install        # installs React, Three.js, @react-three/fiber, @react-three/drei …\nnpm run dev        # opens http://localhost:5173\n```\n\nYou will land on `/` – a list of examples. Click **/basic** to open the first scene. Use **← / →** to move the agent cube; rewards replicate the logic of the original `BasicController` script:\n\n* Each step: **−0.01**\n* Small goal (position 7): **+0.1** and episode terminates\n* Large goal (position 17): **+1** and episode terminates\n\n### 2. Back-end (optional)\n\nFor browser-only play the API is **not required**. If you want to let external RL algorithms interact with the environment, spin up the FastAPI service:\n\n```bash\ncd api\npip install -r requirements.txt\nuvicorn main:app --reload\n```\n\nEndpoints:\n\n* `POST /basic/reset` → `{ \"position\": 10 }`\n* `POST /basic/step`  → `{ \"position\": int, \"reward\": float, \"done\": bool }`\n\nThe contract mirrors OpenAI Gym (`position` plays the role of the observation).\n\n---\n\n## MineCraft RL + LLM Example - Additional Setup\n\nThe **MineCraft** example (#11) combines reinforcement learning with large language models (LLMs) for intelligent agent behavior. This requires additional setup beyond the basic installation.\n\n### Option 1: Local Ollama (Recommended for Development)\n\n1. **Install Ollama**: Download and install from [ollama.ai](https://ollama.ai/)\n\n2. **Pull the required model**:\n   ```bash\n   ollama pull gemma3n:latest\n   ```\n\n3. **Configure the example**: In `api/examples/minecraft.py`, set:\n   ```python\n   USE_LOCAL_OLLAMA = True\n   ```\n\n4. **Start Ollama**: Make sure Ollama is running locally (usually starts automatically)\n\n### Option 2: OpenRouter (Cloud-based)\n\n1. **Get an OpenRouter API key**: Sign up at [openrouter.ai](https://openrouter.ai/) and get your API key\n\n2. **Set environment variable**:\n   ```bash\n   export OPENROUTER_API_KEY=\"your_api_key_here\"\n   ```\n\n3. **Configure the example**: In `api/examples/minecraft.py`, set:\n   ```python\n   USE_LOCAL_OLLAMA = False\n   ```\n\n4. **Note**: This option uses `anthropic/claude-sonnet-4` and requires credits/tokens\n\n### Additional Dependencies\n\nThe MineCraft example also requires additional Python packages for embeddings and LLM functionality. Make sure these are included in your `api/requirements.txt`:\n\n```\nsentence-transformers  # for text embeddings\nopenai                 # for LLM API calls (if using OpenRouter)\n```\n\n### Running the MineCraft Example\n\n1. Start the API with LLM support:\n   ```bash\n   cd api\n   pip install -r requirements.txt\n   uvicorn main:app --reload\n   ```\n\n2. Open the frontend and navigate to the MineCraft example\n\n3. The agents will use LLMs for strategic decision-making, communication, and trading while using RL for basic movement and mining actions.\n\n---\n\n\n[![Star History Chart](https://api.star-history.com/svg?repos=lukehollis/three-mlagents\u0026type=Date)](https://star-history.com/#lukehollis/three-mlagents\u0026Date)\n\n---\n\n## License\n\nMIT © 2025\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukehollis%2Fthree-mlagents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukehollis%2Fthree-mlagents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukehollis%2Fthree-mlagents/lists"}