Metadata-Version: 2.4
Name: ursa-ai
Version: 0.16.2
Summary: Agents for science at LANL
Author-email: Mike Grosskopf <mikegros@lanl.gov>, Nathan Debardeleben <ndebard@lanl.gov>, Rahul Somasundaram <rsomasundaram@lanl.gov>, Isaac Michaud <imichaud@lanl.gov>, Avanish Mishra <avanish@lanl.gov>, Pascal Grosset <pascalgrosset@lanl.gov>, Arthur Lui <alui@lanl.gov>, Russell Bent <rbent@lanl.gov>, Alex Wadell <awadell@lanl.gov>, Jemma Stachelek <jsta@lanl.gov>, Earl Lawrence <earl@lanl.gov>
License-Expression: BSD-3-Clause
Project-URL: Homepage, https://github.com/lanl/ursa
Project-URL: Documentation, https://github.com/lanl/ursa/tree/main/docs
Project-URL: Repository, https://github.com/lanl/ursa
Project-URL: Issues, https://github.com/lanl/ursa/issues
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: arxiv<3.0,>=2.2.0
Requires-Dist: beautifulsoup4<5.0,>=4.13.4
Requires-Dist: randomname<0.3,>=0.2.1
Requires-Dist: pillow<12.0,>=11.3.0
Requires-Dist: pymupdf<2.0,>=1.28.0
Requires-Dist: pymupdf4llm<1.0,>=0.3.4
Requires-Dist: rich<14.0,>=13.9.4
Requires-Dist: ddgs>=9.5.5
Requires-Dist: typer>=0.16.1
Requires-Dist: truststore<1.0,>=0.10.4
Requires-Dist: selectolax<0.5,>=0.4.0
Requires-Dist: langchain>=1.3.2
Requires-Dist: langchain-chroma>=1.0.0
Requires-Dist: langchain-community>=0.4.1
Requires-Dist: langchain-openai>=1.0.1
Requires-Dist: langgraph-checkpoint-sqlite>=3.0.3
Requires-Dist: aiosqlite>=0.20.0
Requires-Dist: langchain-anthropic>=1.4
Requires-Dist: langchain-google-genai>=4.2
Requires-Dist: langchain-text-splitters>=1.0.0
Requires-Dist: langchain-ollama>=1.0.0
Requires-Dist: langchain-mcp-adapters<0.2,>=0.1.12
Requires-Dist: pydantic<3.0,>=2.12.0
Requires-Dist: mcp<2.0,>=1.20.0
Requires-Dist: jsonargparse>=4.45.0
Requires-Dist: fastmcp~=3.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: justext>=3.0.2
Provides-Extra: dashboard
Requires-Dist: fastapi>=0.120.0; extra == "dashboard"
Requires-Dist: uvicorn>=0.37.0; extra == "dashboard"
Provides-Extra: fm
Requires-Dist: torch>=2.9.0; extra == "fm"
Provides-Extra: lammps
Requires-Dist: atomman>=1.5.2; extra == "lammps"
Requires-Dist: trafilatura<1.7,>=1.6.1; extra == "lammps"
Provides-Extra: office-readers
Requires-Dist: python-docx>=1.2; extra == "office-readers"
Requires-Dist: python-pptx>=1.0.2; extra == "office-readers"
Provides-Extra: opt
Requires-Dist: ortools<9.15,>=9.14; extra == "opt"
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp>=1.39.0; extra == "otel"
Requires-Dist: opentelemetry-sdk>=1.38.0; extra == "otel"
Provides-Extra: dsi
Requires-Dist: dsi-workflow>=1.1.4; extra == "dsi"
Provides-Extra: image
Requires-Dist: pillow<12.0.0,>=11.3.0; extra == "image"
Provides-Extra: mp
Requires-Dist: mp-api<0.45.13,>=0.45.8; extra == "mp"
Provides-Extra: metric-plots
Requires-Dist: matplotlib>=3.10.6; extra == "metric-plots"
Requires-Dist: pandas<3.0,>=2.3.1; extra == "metric-plots"
Requires-Dist: scipy<2.0.0,>=1.16.2; extra == "metric-plots"
Dynamic: license-file

# URSA - The Universal Research and Scientific Agent

<img src="https://github.com/lanl/ursa/raw/main/logos/logo.png" alt="URSA Logo" width="200" height="200">

[![PyPI Version][pypi-version]](https://pypi.org/project/ursa-ai/)
[![PyPI Downloads][monthly-downloads]](https://pypistats.org/packages/ursa-ai)

The flexible agentic workflow for accelerating scientific tasks.
Composes information flow between agents for planning, code writing and execution, and online research to solve complex problems.

The original ArXiv paper is [here](https://arxiv.org/abs/2506.22653).

## Documentation

Detailed documenation including:
- Installation
- Getting Started Guides
- Configuration
- ... and more

are located at: [URSA Documentation](https://lanl.github.io/ursa)


## Installation

URSA is published on PyPI as [`ursa-ai`](https://pypi.org/project/ursa-ai/) and supports Python 3.11 or newer.
You can install it with `uv` or `pip`; `uv` is recommended for new projects.

## Documentation and examples

The MkDocs documentation in `docs/` is organized around installation, getting started, configuration, persistence, agents, best practices, and reference material. The `examples/` folder demonstrates practical workflows and ways to pass results from one agent to another.


## Command Line Usage

You can install `ursa` as a command line app with `pip install`; or with [`uv`](https://docs.astral.sh/uv/) via

```bash
uv tool install ursa-ai
```

A reusable YAML configuration file is the preferred way to select endpoints and runtime settings. For example:

```yaml
llm_model:
  model: openai:gpt-5.2
  api_key_env: OPENAI_API_KEY
workspace: .
```

Then start the command line app with:

```
ursa --config config.yaml
```

This will start a REPL in your terminal.

```
  __  ________________ _
 / / / / ___/ ___/ __ `/
/ /_/ / /  (__  ) /_/ /
\__,_/_/  /____/\__,_/

For help, type: ? or help. Exit with Ctrl+d.
ursa>
```

Within the REPL, you can get help by typing `?` or `help`.

You can chat with an LLM by simply typing into the terminal.

```
ursa> How are you?
Thanks for asking! I’m doing well. How are you today? What can I help you with?
```

You can run various agents by typing the name of the agent. For example,

```
ursa> plan
plan: Write a python script to do linear regression using only numpy.
```

Or by prepending the agent name to the query:

```shell
ursa> plan Write a python script to do linear regression using only numpy.
```

If you run subsequent agents, the last output will be appended to the prompt for the next agent.

So, to run the Planning Agent followed by the Execution Agent:
```
ursa> plan
plan: Write a python script to do linear regression using only numpy.

...

ursa> execute
execute: Execute the plan.
```

You can get a list of available command line options via
```
ursa --help
```

### Web Dashboard

The URSA web interface can be launched with:
```
ursa-dashboard
```

or with 
```
ursa-dashboard --host 127.0.0.1 --port 8080
```

This requires installing with the optional `[dashboard]` dependencies.

## Development Team

URSA has been developed at Los Alamos National Laboratory as part of the ArtIMis project.

<img src="https://github.com/lanl/ursa/raw/main/logos/artimis.png" alt="ArtIMis Logo" width="200" height="200">

### Notice of Copyright Assertion (O4958):
*This program is Open-Source under the BSD-3 License.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:*
- *Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.*
- *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.*
- *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.*

THIS 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.

[pypi-version]: https://img.shields.io/pypi/v/ursa-ai?style=flat-square&label=PyPI
[monthly-downloads]: https://img.shields.io/pypi/dm/ursa-ai?style=flat-square&label=Downloads&color=blue
