{"id":34087088,"url":"https://github.com/lanl/ursa","last_synced_at":"2026-04-08T13:31:44.100Z","repository":{"id":310013201,"uuid":"1038321975","full_name":"lanl/ursa","owner":"lanl","description":"Universal Research and Scientific Agent","archived":false,"fork":false,"pushed_at":"2026-04-01T21:50:43.000Z","size":12446,"stargazers_count":42,"open_issues_count":27,"forks_count":26,"subscribers_count":4,"default_branch":"main","last_synced_at":"2026-04-02T09:26:25.161Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://lanl.github.io/ursa","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lanl.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":"COPYRIGHT","agents":null,"dco":null,"cla":null}},"created_at":"2025-08-15T01:46:33.000Z","updated_at":"2026-04-01T21:50:47.000Z","dependencies_parsed_at":"2025-09-19T01:04:05.790Z","dependency_job_id":"1ee752f1-01af-4535-8547-756d1cd4cbd0","html_url":"https://github.com/lanl/ursa","commit_stats":null,"previous_names":["lanl/ursa"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/lanl/ursa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fursa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fursa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fursa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fursa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lanl","download_url":"https://codeload.github.com/lanl/ursa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lanl%2Fursa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31558380,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T10:21:54.569Z","status":"ssl_error","status_checked_at":"2026-04-08T10:21:38.171Z","response_time":54,"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":[],"created_at":"2025-12-14T13:36:41.525Z","updated_at":"2026-04-08T13:31:44.081Z","avatar_url":"https://github.com/lanl.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# URSA - The Universal Research and Scientific Agent\n\n\u003cimg src=\"https://github.com/lanl/ursa/raw/main/logos/logo.png\" alt=\"URSA Logo\" width=\"200\" height=\"200\"\u003e\n\n[![PyPI Version][pypi-version]](https://pypi.org/project/ursa-ai/)\n[![PyPI Downloads][monthly-downloads]](https://pypistats.org/packages/ursa-ai)\n\nThe flexible agentic workflow for accelerating scientific tasks.\nComposes information flow between agents for planning, code writing and execution, and online research to solve complex problems.\n\nThe original ArXiv paper is [here](https://arxiv.org/abs/2506.22653).\n\n## Installation\nYou can install `ursa` via `pip` or [`uv`](https://docs.astral.sh/uv/). Installing `ursa` in a clean\nenvironment with python 3.11-3.12 may be necessary. (Some `ursa` dependencies\ncurrently do not support `python\u003e=3.13`.)\n\n**uv**\n\n```sh\nuv init -p 3.12  # or 3.11\nuv add ursa-ai\n```\n\n**pip**\n\n```sh\npip install ursa-ai\n```\n\n**conda with pip install**\n\n```sh\nconda create -y -n ursa-env python=3.12  # or 3.11\nconda run --live-stream -n ursa-env python -m pip install ursa-ai\n```\n\n## How to use this code\nBetter documentation will be incoming, but for examples in the `examples/`\nfolder demonstrates how to set up some basic problems. They also should give\nsome idea of how to pass results from one agent to another. I will look to add\nthings with multi-agent graphs, etc. in the future.\n\nDocumentation for each URSA agent:\n- [Planning Agent](docs/planning_agent.md)\n- [Execution Agent](docs/execution_agent.md)\n- [ArXiv Agent](docs/arxiv_agent.md)\n- [DSI Agent](docs/dsi_agent.md)\n- [Web Search Agent](docs/web_search_agent.md)\n- [Hypothesizer Agent](docs/hypothesizer_agent.md)\n\nDocumentation for combining agents:\n- [ArXiv -\u003e Execution for Materials](docs/combining_arxiv_and_execution.md)\n- [ArXiv -\u003e Execution for Neutron Star Properties](docs/combining_arxiv_and_execution_neutronStar.md)\n\n\n## Command Line Usage\n\nYou can install `ursa` as a command line app with `pip install`; or with [`uv`](https://docs.astral.sh/uv/) via\n\n```bash\nuv tool install ursa-ai\n```\n\nTo use the command line app, run\n\n```\nursa --llm_model.model openai:gpt-5.2\n```\n\nThis will start a REPL in your terminal.\n\n```\n  __  ________________ _\n / / / / ___/ ___/ __ `/\n/ /_/ / /  (__  ) /_/ /\n\\__,_/_/  /____/\\__,_/\n\nFor help, type: ? or help. Exit with Ctrl+d.\nursa\u003e\n```\n\nWithin the REPL, you can get help by typing `?` or `help`.\n\nYou can chat with an LLM by simply typing into the terminal.\n\n```\nursa\u003e How are you?\nThanks for asking! I’m doing well. How are you today? What can I help you with?\n```\n\nYou can run various agents by typing the name of the agent. For example,\n\n```\nursa\u003e plan\nplan: Write a python script to do linear regression using only numpy.\n```\n\nOr by prepending the agent name to the query:\n\n```shell\nursa\u003e plan Write a python script to do linear regression using only numpy.\n```\n\nIf you run subsequent agents, the last output will be appended to the prompt for the next agent.\n\nSo, to run the Planning Agent followed by the Execution Agent:\n```\nursa\u003e plan\nplan: Write a python script to do linear regression using only numpy.\n\n...\n\nursa\u003e execute\nexecute: Execute the plan.\n```\n\nYou can get a list of available command line options via\n```\nursa --help\n```\n\n### Web Dashboard\n\nThe URSA web interface can be launched with:\n```\nursa-dashboard\n```\n\nor with \n```\nursa-dashboard --host 127.0.0.1 --port 8080\n```\n\nThis requires installing with the optional `[dashboard]` dependencies.\n\n### Configuring URSA\n\nSee the example [configuration file](./configs/example.yaml) and [documentation](./configs/README.md) for more details.\n\n## URSA MCP Server\n\nYou can connect `ursa` as an [Model Context Protocol](https://modelcontextprotocol.io) Server\nto other agentic frameworks or interfaces. To start the MCP server, run:\n\n\n```shell\nursa mcp-server --transport streamable-http\n```\n\nThis will start an MCP server on localhost on port 8000.\n\n\u003e [!WARNING]\n\u003e The MCP Server does not isolate sessions from one another. As such, using the server in a multi-user context\n\u003e is not recommended.\n\n\n### MCP Inspector\n\nAfter installing the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector), you can test the Ursa MCP server by running:\n\n```shell\nnpx @modelcontextprotocol/inspector \\\n    uv run ursa mcp-server\n```\n\nOr by connecting to an existing MCP server using the `streamable-http` transport by running:\n\n```shell\nnpx @modelcontextprotocol/inspector \\\n    --transport http \\\n    --server-url http://localhost:8000/mcp\n```\n\n\nYou can test the server using curl from another terminal:\n\n\nThe MCP server configuration options can be seen with:\n```\nursa mcp-server --help\n```\n\nThe served instance of ursa can be configured via a configuration file (`ursa --config config.yaml mcp-server...`)\nor command line arguments (`ursa --llm_model.model openai:gpt-5 ... mcp-server ...`).\n\n\n## Sandboxing\nThe Execution Agent is allowed to run system commands and write/run code. Being able to execute arbitrary system commands or write\nand execute code has the potential to cause problems like:\n- Damage code or data on the computer\n- Damage the computer\n- Transmit your local data\n\nThe Web Search Agent scrapes data from urls, so has the potential to attempt to pull information from questionable sources.\n\nSome suggestions for sandboxing the agent:\n- Creating a specific environment such that limits URSA's access to only what you want. Examples:\n    - Creating/using a virtual machine that is sandboxed from the rest of your machine\n    - Creating a new account on your machine specifically for URSA\n- Creating a network blacklist/whitelist to ensure that network commands and webscraping are contained to safe sources\n\nYou have a duty for ensuring that you use URSA responsibly.\n\n## Container image\n\nTo enable limited sandboxing insofar as containerization does this, you can run\nthe following commands:\n\n### Docker\n\n```shell\n# Pull the image\ndocker pull ghcr.io/lanl/ursa\n\n# Run script from host system\nmkdir -p scripts\necho \"import ursa; print('Hello from ursa')\" \u003e scripts/my_script.py\ndocker run -e \"OPENAI_API_KEY\"=$OPENAI_API_KEY \\\n    --mount type=bind,src=$PWD/scripts,dst=/mnt/workspace \\\n    ghcr.io/lanl/ursa \\\n    bash -c \"uv run /mnt/workspace/my_script.py\"\n```\n\n### Charliecloud\n\n[Charliecloud](https://charliecloud.io/) is a rootless alternative to docker\nthat is sometimes preferred on HPC. The following commands replicate the\nbehaviors above for docker.\n\n```shell\n# Pull the image\nch-image pull ghcr.io/lanl/ursa ursa\n\n# Convert image to sqfs, for use on another system\nch-convert ursa ursa.sqfs\n\n# Run script from host system (if wanted, replace ursa with /path/to/ursa.sqfs)\nmkdir -p scripts\necho \"import ursa; print('Hello from ursa')\" \u003e scripts/my_script.py\nch-run -W ursa \\\n    --unset-env=\"*\" \\\n    --set-env \\\n    --set-env=\"OPENAI_API_KEY\"=$OPENAI_API_KEY \\\n    --bind ${PWD}/scripts:/mnt/workspace \\\n    --cd /mnt/workspace \\\n    -- bash -c \\\n    \"uv run --no-sync my_script.py\"\n```\n\n## Development Dependencies\n\n* [`uv`](https://docs.astral.sh/uv/)\n    * `uv` is an extremely fast python package and project manager, written in Rust.\n      Follow installation instructions\n      [here](https://docs.astral.sh/uv/getting-started/installation/)\n\n* [`ruff`](https://docs.astral.sh/ruff/)\n    * An extremely fast Python linter and code formatter, written in Rust.\n    * After installing `uv`, you can install ruff with `uv tool install ruff`\n\n* [`just`](https://github.com/casey/just)\n    * A modern way to save and run project-specific commands\n    * After installing `uv`, you can install just with `uv tool install rust-just`\n\n## Development Team\n\nURSA has been developed at Los Alamos National Laboratory as part of the ArtIMis project.\n\n\u003cimg src=\"https://github.com/lanl/ursa/raw/main/logos/artimis.png\" alt=\"ArtIMis Logo\" width=\"200\" height=\"200\"\u003e\n\n### Notice of Copyright Assertion (O4958):\n*This program is Open-Source under the BSD-3 License.\nRedistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:*\n- *Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.*\n- *Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.*\n- *Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.*\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.\n\n[pypi-version]: https://img.shields.io/pypi/v/ursa-ai?style=flat-square\u0026label=PyPI\n[monthly-downloads]: https://img.shields.io/pypi/dm/ursa-ai?style=flat-square\u0026label=Downloads\u0026color=blue\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fursa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flanl%2Fursa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flanl%2Fursa/lists"}