{"id":29599717,"url":"https://github.com/basisresearch/maraprotocol","last_synced_at":"2025-07-20T11:34:16.257Z","repository":{"id":305027668,"uuid":"1021662714","full_name":"BasisResearch/MARAProtocol","owner":"BasisResearch","description":null,"archived":false,"fork":false,"pushed_at":"2025-07-17T20:53:18.000Z","size":369,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-07-17T22:51:46.132Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"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/BasisResearch.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}},"created_at":"2025-07-17T18:37:06.000Z","updated_at":"2025-07-17T20:46:27.000Z","dependencies_parsed_at":"2025-07-18T01:24:37.181Z","dependency_job_id":"99fc012a-2800-4e02-91f5-4ec263cda0d9","html_url":"https://github.com/BasisResearch/MARAProtocol","commit_stats":null,"previous_names":["basisresearch/maraprotocol"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/BasisResearch/MARAProtocol","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasisResearch%2FMARAProtocol","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasisResearch%2FMARAProtocol/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasisResearch%2FMARAProtocol/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasisResearch%2FMARAProtocol/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BasisResearch","download_url":"https://codeload.github.com/BasisResearch/MARAProtocol/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BasisResearch%2FMARAProtocol/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":266117923,"owners_count":23879146,"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","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":[],"created_at":"2025-07-20T11:34:15.746Z","updated_at":"2025-07-20T11:34:16.242Z","avatar_url":"https://github.com/BasisResearch.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MARAProtocol\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nThis is used as blueprint to implement MARAProtocol. The protocol is designed to be a language-agnostic interface to implement MARA environments and agents.\n**MARAProtocol** is an open, language-agnostic interface built on Protocol Buffers that standardizes how interactive environments and learning agents exchange observations, actions, and rewards, no matter which programming language or domain they use. To do this, MARA protocols are currently defined in Protobuf.\nBy separating runtime orchestration from domain logic and shipping ready-made stubs, evaluation tooling, and a growing benchmark suite, it lets environment builders plug in new tasks quickly while enabling agent developers to test and compare algorithms across heterogeneous, high-bandwidth domains—from robotics to Autumn video-game worlds.\n\nThe protocols are stored in `protocols/*.proto` files. \n\n## Table of Contents\n- Installation\n- Examples\n- License\n\n## Installation\n### Requirements\n- Python \u003e= 3.12 (see note on 3.13 pre-release)  \n- `protoc` \u003e= 3.0  \n- macOS/Linux (Windows instructions TBD)\n\nTo install these dependencies and generate the corresponding Python stubs and library for implementing environments and agents, please execute the following scripts:\n\n```bash\ngit clone https://github.com/BasisResearch/MARAProtocol.git\ncd MARAProtocol\nsh setup_script_mac.sh           # installs deps\nsh scripts/generate_python.sh     # generates gRPC stubs into ./generated\n```\n\n### Obtaining the interpreter\nWe have a prebuilt interpreter for Python 3.13 on MacOSX. More prebuilts are available at [Autumn.cpp/Autumn.wasm repository](https://github.com/BasisResearch/Autumn.cpp/releases). For any different versions, please follow the build guide of the repository.\n\n### Setting up environment variables\nFollowing this, please create an `.env` file following the `.env_sample`. This file is mostly used for providing credentials for LLM Agents.\nOur supported LLM Agents includes (and will grow if needed): Ollama, OpenAI, Claude, MLX, Gemini. We also support framework OpenRouter framework for easily switch between different LLM providers.\n\nYou can also setup the API key directly, for example:\n```bash\nexport OPENROUTER_API_KEY=\"YOUR_API_KEY_HERE\"\n```\n\nWe list the corresponding providers belows for quick start.\n\n| **Provider**       | **Docs / Quick-start**                                                                         |\n| ------------------ | ---------------------------------------------------------------------------------------------- |\n| Ollama             | [REST API reference](https://ollama.readthedocs.io/en/api/)                                    |\n| OpenAI             | [API key setup](https://help.openai.com/en/articles/5112595-best-practices-for-api-key-safety) |\n| Claude (Anthropic) | [Anthropic Developer Docs](https://docs.anthropic.com/)                                        |\n| Apple MLX          | [MLX GitHub](https://github.com/ml-explore/mlx)                                                |\n| Google Gemini      | [Gemini API docs](https://ai.google.dev/gemini-api/docs)                                       |\n| OpenRouter         | [OpenRouter Quickstart](https://openrouter.ai/docs/quickstart)                                 |\n\nDrop these variables into your local `.env`; the MARAProtocol tooling will load them automatically at runtime.\n\n## Examples\nWe provide several examples:\n1. A standard environment and random agent implementing MARAProtocol as a text adventure in `python_examples/text_adventures`.\n2. [AutumnBench environments](./python_examples/autumnbench/): Next Frame Prediction (NFP), Change Detection (or Defect Detection) and Planning. Along with three types of agents: Random agent, LLM-based agent, and an agent that's built with [AutumnSynth](https://www.basis.ai/blog/autumn/) in mind\n\n### AutumnBench Baselines\nWe also provide an example benchmark for Autumn that consists of a single program, this is stored in [Example Benchmark](./python_examples/autumnbench/example_benchmark/). We tentatively release the script to download the full dataset.\n\nOnce this is done, you can run the agent with either one of the following agents. Note that, protobuf codes are originally meant for creating gRPC for a language-agnostic interface. However, for simplicity, we usethem locally.\n\n\n### Running Agents\n```bash\npython -m python_examples.autumnbench.run_no_server +experiment=debug data_dir=$(pwd)/python_examples/autumnbench/example_benchmark\n```\n\nMore configurable parameters can be found in `python_examples/autumnbench/conf/config.yaml`. You can either specify a new experiment config in `conf/experiments/` or specify them at runtime. For example, to change the render mode you can simply run the following command.\n\n```bash\npython -m python_examples.autumnbench.run_no_server +experiment=debug data_dir=$(pwd)/python_examples/autumnbench/example_benchmark render_mode=image\n```\n\nIf you would like to run with another model (say Claude 4 Opus) on OpenRouter, you can do the following:\n\n```bash\npython -m python_examples.autumnbench.run_no_server +experiment=debug data_dir=/python_examples/autumnbench/example_benchmark=\"anthropic/claude-opus-4\"\n```\n\nYou can also configure the environments you want to run on by changing the list in the `envs` parameter.  For the `task_name` parameter the options supported as `(mfp, dd, planning)`.\n\nThe main agent is the `UnifiedReactAgent` defined in [`llm_agent.py`](./python_examples/autumnbench/llm_agent.py), with some of the prompts defined in [`prompts.py`](./python_examples/autumnbench/prompts.py). The task type themselves are defined in [`concrete_envs.py`](./python_examples/autumnbench/concrete_envs.py). Adding a new environment should be done by adding it to the `AutumnBenchmark` repo directly.\n\nWe currently provide the following three agents:\n- \"autumn_llm_unified_interactive_agent_v1\" # LLM-based agent\n- \"autumn_random_interactive_agent_v1\"      # Random agent\n- \"autumn_simple_wm_agent\"                  # Oracle autumnSynth agent\n\nYou can select the default desired agent in [`config.yaml`](`python_examples/autumnbench/conf/config.yaml`).\n\n# License\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n# Contributors\nDat Nguyen, Moksh Jain, Yichao Liang, Archana Warrier, Michelangelo Naim, Cambridge Yang, Zenna Tavares\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasisresearch%2Fmaraprotocol","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbasisresearch%2Fmaraprotocol","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbasisresearch%2Fmaraprotocol/lists"}