ursa-ai 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

ursa/tools/write_code.py

@@ -4,7 +4,7 @@ from langchain_core.tools import tool
 
 
 @tool
-def write_python(code: str, filename: str, workspace_dir: str):
+def write_python(code: str, filename: str, workspace_dir: str) -> str:
     """
     Writes code to a file in the given workspace.
 

ursa/util/helperFunctions.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any, Callable, Dict, Iterable, List, Union
+
+from langchain_core.messages import AIMessage, BaseMessage, ToolMessage
+from langchain_core.runnables import Runnable
+
+
+# --- if you already have your own versions, reuse them ---
+def _parse_args(v: Any) -> Dict[str, Any]:
+    if v is None:
+        return {}
+    if isinstance(v, dict):
+        return v
+    if isinstance(v, str):
+        try:
+            return json.loads(v)
+        except Exception:
+            return {"_raw": v}
+    return {"_raw": v}
+
+
+def extract_tool_calls(msg: AIMessage) -> List[Dict[str, Any]]:
+    # Prefer normalized field
+    if msg.tool_calls:
+        out = []
+        for tc in msg.tool_calls:
+            name = getattr(tc, "name", None) or tc.get("name")
+            args = getattr(tc, "args", None) or tc.get("args")
+            call_id = getattr(tc, "id", None) or tc.get("id")
+            out.append({"name": name, "args": _parse_args(args), "id": call_id})
+        return out
+
+    # Fallbacks (OpenAI raw payloads)
+    ak = msg.additional_kwargs or {}
+    if ak.get("tool_calls"):
+        out = []
+        for tc in ak["tool_calls"]:
+            fn = tc.get("function", {}) or {}
+            out.append({
+                "name": fn.get("name"),
+                "args": _parse_args(fn.get("arguments")),
+                "id": tc.get("id"),
+            })
+        return out
+
+    if ak.get("function_call"):
+        fn = ak["function_call"]
+        return [
+            {
+                "name": fn.get("name"),
+                "args": _parse_args(fn.get("arguments")),
+                "id": None,
+            }
+        ]
+    return []
+
+
+# -----------------------------------------------------------------------------
+
+
+ToolRegistry = Dict[str, Union[Runnable, Callable[..., Any]]]
+
+
+def _stringify_output(x: Any) -> str:
+    if isinstance(x, str):
+        return x
+    try:
+        return json.dumps(x, ensure_ascii=False)
+    except Exception:
+        return str(x)
+
+
+def _invoke_tool(
+    tool: Union[Runnable, Callable[..., Any]], args: Dict[str, Any]
+) -> Any:
+    # Runnable (LangChain tools & chains)
+    if isinstance(tool, Runnable):
+        return tool.invoke(args)
+    # Plain callable
+    try:
+        return tool(**args)
+    except TypeError:
+        # Some tools expect a single positional payload
+        return tool(args)
+
+
+def run_tool_calls(
+    ai_msg: AIMessage,
+    tools: Union[ToolRegistry, Iterable[Union[Runnable, Callable[..., Any]]]],
+) -> List[BaseMessage]:
+    """
+    Args:
+        ai_msg: The LLM's AIMessage containing tool calls.
+        tools: Either a dict {name: tool} or an iterable of tools (must have `.name`
+               for mapping). Each tool can be a Runnable or a plain callable.
+
+    Returns:
+        out: list[BaseMessage] to feed back to the model
+    """
+    # Build a name->tool map
+    if isinstance(tools, dict):
+        registry: ToolRegistry = tools  # type: ignore
+    else:
+        registry = {}
+        for t in tools:
+            name = getattr(t, "name", None) or getattr(t, "__name__", None)
+            if not name:
+                raise ValueError(f"Tool {t!r} has no discoverable name.")
+            registry[name] = t  # type: ignore
+
+    calls = extract_tool_calls(ai_msg)
+
+    if not calls:
+        return []
+
+    out: List[BaseMessage] = []
+    for call in calls:
+        name = call.get("name")
+        args = call.get("args", {}) or {}
+        call_id = call.get("id") or f"call_{uuid.uuid4().hex}"
+
+        # 1) the AIMessage that generated the call
+        out.append(ai_msg)
+
+        # 2) the ToolMessage with the execution result (or error)
+        if name not in registry:
+            content = f"ERROR: unknown tool '{name}'."
+        else:
+            try:
+                result = _invoke_tool(registry[name], args)
+                content = _stringify_output(result)
+            except Exception as e:
+                content = f"ERROR: {type(e).__name__}: {e}"
+
+        out.append(
+            ToolMessage(content=content, tool_call_id=call_id, name=name)
+        )
+
+    return out

ursa/util/optimization_schema.py

@@ -0,0 +1,78 @@
+from typing import Any, List, Literal, Optional, TypedDict
+
+
+class DecisionVariableType(TypedDict):
+    name: str  # decision variable name
+    type: Literal[
+        "continuous",
+        "integer",
+        "logical",
+        "infinite-dimensional",
+        "finite-dimensional",
+    ]  # decision variable type
+    domain: str  # allowable values of variable
+    description: str  # natural language description
+
+
+class ParameterType(TypedDict):
+    name: str  # parameter name
+    value: Optional[Any]  # parameter value; None
+    description: str  # natural language description
+    is_user_supplied: bool  # 1 if user supplied parameter
+
+
+class ObjectiveType(TypedDict):
+    sense: Literal["minimize", "maximize"]  # objective sense
+    expression_nl: str  # sympy-representable mathematical expression
+    tags: List[
+        Literal["linear", "quadratic", "nonlinear", "convex", "nonconvex"]
+    ]  # objective type
+
+
+class ConstraintType(TypedDict):
+    name: str  # constraint name
+    expression_nl: str  # sympy-representable mathematical expression
+    tags: List[
+        Literal[
+            "linear",
+            "integer",
+            "nonlinear",
+            "equality",
+            "inequality",
+            "infinite-dimensional",
+            "finite-dimensional",
+        ]
+    ]  # constraint type
+
+
+class NotesType(TypedDict):
+    verifier: str  # problem verification status and explanation
+    feasibility: str  # problem feasibility status
+    user: str  # notes to user
+    assumptions: str  # assumptions made during formulation
+
+
+class ProblemSpec(TypedDict):
+    title: str  # name of the problem
+    description_nl: str  # natural language description
+    decision_variables: List[
+        DecisionVariableType
+    ]  # list of all decision variables
+    parameters: List[ParameterType]  # list of all parameters
+    objective: ObjectiveType  # structred objective function details
+    constraints: List[ConstraintType]  # structured constraint details
+    problem_class: Optional[str]  # optimization problem class
+    latex: Optional[str]  # latex formulation of the problem
+    status: Literal["DRAFT", "VERIFIED", "ERROR"]  # problem status
+    notes: NotesType  # structured notes data
+
+
+class SolverSpec(TypedDict):
+    solver: str  # name of the solver, replace with Literal["Gurobi","Ipopt",...] to restrict solvers
+    library: str  # library or relevant packages for the solver
+    algorithm: Optional[str]  # algorithm used to solve the problem
+    license: Optional[
+        str
+    ]  # License status of the solver (open-source, commercial,etc.)
+    parameters: Optional[List[dict]]  # other parameters relevant to the problem
+    notes: Optional[str]  # justifying the choice of solver

ursa/util/parse.py

@@ -2,7 +2,7 @@ import json
 import re
 
 
-def extract_json(text: str):
+def extract_json(text: str) -> list[dict]:
     """
     Extract a JSON object or array from text that might contain markdown or other content.
 

{ursa_ai-0.5.0.dist-info → ursa_ai-0.6.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ursa-ai
-Version: 0.5.0
+Version: 0.6.0
 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>, Arthur Lui <alui@lanl.gov>, Russell Bent <rbent@lanl.gov>, Earl Lawrence <earl@lanl.gov>
 License-Expression: BSD-3-Clause
@@ -38,8 +38,7 @@ Requires-Dist: langchain-anthropic<0.4,>=0.3.19
 Requires-Dist: langgraph-checkpoint-sqlite<3.0,>=2.0.10
 Requires-Dist: langchain-ollama<0.4,>=0.3.6
 Requires-Dist: ddgs>=9.5.5
-Requires-Dist: atomman>=1.5.2
-Requires-Dist: trafilatura>=1.6.1
+Requires-Dist: typer>=0.16.1
 Dynamic: license-file
 
 # URSA - The Universal Research and Scientific Agent
@@ -81,7 +80,68 @@ Documentation for combining agents:
 - [ArXiv -> Execution for Materials](docs/combining_arxiv_and_execution.md)
 - [ArXiv -> Execution for Neutron Star Properties](docs/combining_arxiv_and_execution_neutronStar.md)
 
-# Sandboxing
+
+## Command line usage
+
+You can install `ursa` as a command line app with `pip install`; or with `uv` via
+
+```bash
+uv tool install ursa-ai
+```
+
+To use the command line app, run
+
+```
+ursa run
+```
+
+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
+Enter your prompt for Planning Agent: 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
+Enter your prompt for Planning Agent: Write a python script to do linear regression using only numpy.
+
+...
+
+ursa> execute
+Enter your prompt for Execution Agent: Execute the plan.
+```
+
+You can get a list of available command line options via
+```
+ursa run --help
+```
+
+## Sandboxing
 The Execution Agent is allowed to run system commands and write/run code. Being able to execute arbitrary system commands or write
 and execute code has the potential to cause problems like:
 - Damage code or data on the computer
@@ -98,6 +158,65 @@ Some suggestions for sandboxing the agent:
 
 You have a duty for ensuring that you use URSA responsibly.
 
+## Container image
+
+To enable limited sandboxing insofar as containerization does this, you can run
+the following commands:
+
+### Docker
+
+```shell
+# Build a local container using the Docker runtime
+docker buildx build --progress=plain -t ursa .
+
+# Run included example
+docker run -e "OPENAI_API_KEY"=$OPENAI_API_KEY ursa \
+    bash -c "uv run python examples/single_agent_examples/execution_agnet/integer_sum.py"
+
+# Run script from host system
+mkdir -p scripts
+echo "import ursa; print('Hello from ursa')" > scripts/my_script.py
+docker run -e "OPENAI_API_KEY"=$OPENAI_API_KEY \
+    --mount type=bind,src=$PWD/scripts,dst=/mnt/workspace \
+    ursa \
+    bash -c "uv run /mnt/workspace/my_script.py"
+```
+
+### Charliecloud
+
+[Charliecloud](https://charliecloud.io/) is a rootless alternative to docker
+that is sometimes preferred on HPC. The following commands replicate the
+behaviors above for docker.
+
+```shell
+# Build a local container using the Docker runtime
+ch-image build -t ursa
+
+# Convert image to sqfs, for use on another system
+ch-convert ursa ursa.sqfs
+
+# Run included example (if wanted, replace ursa with /path/to/ursa.sqfs)
+ch-run -W ursa \
+    --unset-env="*" \
+    --set-env \
+    --set-env="OPENAI_API_KEY"=$OPENAI_API_KEY \
+    --cd /app \
+    -- bash -c \
+    "uv run python examples/single_agent_examples/execution_agnet/integer_sum.py"
+
+# Run script from host system (if wanted, replace ursa with /path/to/ursa.sqfs)
+mkdir -p scripts
+echo "import ursa; print('Hello from ursa')" > scripts/my_script.py
+ch-run -W ursa \
+    --unset-env="*" \
+    --set-env \
+    --set-env="OPENAI_API_KEY"=$OPENAI_API_KEY \
+    --bind ${PWD}/scripts:/mnt/workspace \
+    --cd /app \
+    -- bash -c \
+    "uv run python /mnt/workspace/integer_sum.py"
+```
+
 ## Development Dependencies
 
 * [`uv`](https://docs.astral.sh/uv/)

ursa_ai-0.6.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+ursa/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ursa/agents/__init__.py,sha256=u5ClncJ-w4nIJLQJTOC-NBv6Hu4pXxALgZJJxDt3tZw,1202
+ursa/agents/arxiv_agent.py,sha256=naXZuPd3tHuyjqoldsN1gJXWcGB6GJaEdtEzfP1JO1w,14570
+ursa/agents/base.py,sha256=XZ62XhF-GdMykdUyiMuxqQwt41hrryaK9aBhgIFJMMQ,14482
+ursa/agents/code_review_agent.py,sha256=F3RJmS1jBYOoWPg5Hiy-xirutLTtw_u1_hqiKIsA2eY,11563
+ursa/agents/execution_agent.py,sha256=gMQsiNoj8feG3kalcVs39AV58GXrfvq6jff3m2ecyyw,17923
+ursa/agents/hypothesizer_agent.py,sha256=2jSOHkR8MjNhS5HMeOhZCkhT4wGDLNBs-aLgQhYBHr4,23124
+ursa/agents/lammps_agent.py,sha256=z7RbZwk70aC31CyagXk3LyPhtU4IInUMMa1v8r2qji4,14774
+ursa/agents/mp_agent.py,sha256=HvD4JC9OuGeEicW3mKZBQmQ1yn0HVB03118E1urXwx4,6833
+ursa/agents/optimization_agent.py,sha256=siJKyujfy_oNQDbnIFaCUkE_DLvmxPYsBJBDms6Cgbg,13945
+ursa/agents/planning_agent.py,sha256=9XwwmcEtNHW8xd4osljawp1V0X4y9t3R6ncHrsPo1eo,6489
+ursa/agents/rag_agent.py,sha256=kc7ZYWxgWNh-LbMpREaJY90IVbs2SKPrXdCutxrEdT0,10099
+ursa/agents/recall_agent.py,sha256=MoS0FaQFAb14DeYSCo6sYKNTjvE_u-egTOvuXSTXLpk,1693
+ursa/agents/websearch_agent.py,sha256=7d9EL9r2vqlJHwU1nOeV_moc0p4Jxbfz2awOMrKsf0k,7759
+ursa/cli/__init__.py,sha256=YYh7E1Ce3fcJaYn1XP19U1d9iHG1INfnMQ6gAhtARKM,3879
+ursa/cli/hitl.py,sha256=NIKr72fIdwXE_g6KtRc6c94zSRvft2Ptyi4F0UPSBI8,14695
+ursa/observability/pricing.py,sha256=wNe51EcYjk3KDSuU8rv_vjOPlGZB3We_dQrVBcPXdWA,10551
+ursa/observability/timing.py,sha256=yQX5ZtkxRBH_1V61KjWmEBph02DOeZuP-v0-OtJNffQ,48612
+ursa/prompt_library/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ursa/prompt_library/code_review_prompts.py,sha256=-HuhwW9W_p2LDn44bXLntxLADHCOyl-2KIXxRHto66w,2444
+ursa/prompt_library/execution_prompts.py,sha256=bJpRPBW-6d41amqC5DXqcIwsoOPpMvY7ZMNGVsJWgII,2388
+ursa/prompt_library/hypothesizer_prompts.py,sha256=ieupOF5tUy_u8actOjPbK-y5Qkrgw6EYxAfw6RXBebs,762
+ursa/prompt_library/literature_prompts.py,sha256=zhBiN3Q-1Z2hp-hkXXp0T8Ipc-6YUM9gw85DjNu1F6I,421
+ursa/prompt_library/optimization_prompts.py,sha256=n3fNBsG0hmggAMPb5R7t2lyxBLQt1E_udXM0bAl8Jz4,7929
+ursa/prompt_library/planning_prompts.py,sha256=C8IfVc3ny_5-03bJZop2Yax7wfqS_UIdUGsTZSNQRC0,3534
+ursa/prompt_library/websearch_prompts.py,sha256=n4DJaYn_lIYAVtdy00CCJjT-dLWhn2JNipYqMJAotdY,8846
+ursa/tools/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ursa/tools/feasibility_checker.py,sha256=Tboc_3vDx8Pb-cs56SfiXOsayLz8AkXyicfz6puKZ_U,4172
+ursa/tools/feasibility_tools.py,sha256=Drr3L238hzXieNIzQ0UNfrn66mZon7YnM_diSgU9KQw,36921
+ursa/tools/run_command.py,sha256=sQRuHtRyJYWEyL9dpW_Ukc-xQ5vmKKJK1i_6z3uKEfA,690
+ursa/tools/write_code.py,sha256=cDUJ6nPUfUmr7Fz2PwYUzawWm05V40cTyWNhUU5dfqo,1227
+ursa/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ursa/util/diff_renderer.py,sha256=1L1q2qWWb8gLhR532-LgJn2TrqXDx0gUpPVOWD_sqeU,4086
+ursa/util/helperFunctions.py,sha256=cs-pQEcXyOr4nb5FoH9Ssg3hktycEapW07-MKJcUNOA,4122
+ursa/util/memory_logger.py,sha256=GiKYbQBpxlNRLKyqKFJyrbSbVCkXpRB7Yr5so43tUAw,6097
+ursa/util/optimization_schema.py,sha256=b2wO0BjCIgQb15Q3adDu-ZyG3dfncme9OGQw6FmDGDc,2731
+ursa/util/parse.py,sha256=bTC582fAJDWozXU1XGq4WpY2KR1GnAKVC6kTDFh-kXk,2825
+ursa_ai-0.6.0.dist-info/licenses/LICENSE,sha256=4Vr6_u2zTHIUvYjoOBg9ztDbfpV3hyCFv3mTCS87gYU,1482
+ursa_ai-0.6.0.dist-info/METADATA,sha256=mF5Zzp0hlS7pu03hAoN2FlhNiyjtUzduUPOPF9dDVZw,9885
+ursa_ai-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+ursa_ai-0.6.0.dist-info/entry_points.txt,sha256=B0bbgM-NcAqLujZ1lfmChJZpQMYQDYFJck4moU89Y4E,39
+ursa_ai-0.6.0.dist-info/top_level.txt,sha256=OjA1gRYSUAeiXGnpqPC8iOOGfcjFO1IlP848qMnYSdY,5
+ursa_ai-0.6.0.dist-info/RECORD,,

ursa_ai-0.6.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ursa = ursa.cli:main

ursa_ai-0.5.0.dist-info/RECORD

@@ -1,28 +0,0 @@
-ursa/agents/__init__.py,sha256=u5ClncJ-w4nIJLQJTOC-NBv6Hu4pXxALgZJJxDt3tZw,1202
-ursa/agents/arxiv_agent.py,sha256=kiRPshNI-fR-uEFZGp6dyfQ38sIFFb6rUiiNVw3lAXc,13494
-ursa/agents/base.py,sha256=uFhRLVzqhFbTZVA7IePKbUi03ATCXuvga7rzwaHy1B0,1321
-ursa/agents/code_review_agent.py,sha256=aUDq5gT-jdl9Qs-Wewj2oz1d60xov9sN-DOYRfGNTU0,11550
-ursa/agents/execution_agent.py,sha256=okVTsZhG0S92evHtmxge3Ymq3pH0QLYY2VqzO39WG5Y,16581
-ursa/agents/hypothesizer_agent.py,sha256=pUwFDWGBJAqL7CDXxWYJrQrknC3DgRe82Poc_Q_OSMg,23193
-ursa/agents/lammps_agent.py,sha256=16eKOtAXEm-clnIZcfEaoxQONqbUJm_1dZhZhm2C2uM,14099
-ursa/agents/mp_agent.py,sha256=UyJSheMGHZpWQJL3EgYgPPqArfv6F8sndN05q4CPtyo,6015
-ursa/agents/planning_agent.py,sha256=ayyNDQifPvYtQ-JYnFk3TaXWZcd_6k8qUheJGariqG8,5574
-ursa/agents/rag_agent.py,sha256=kEL5F3lZeSKtdXXyUWlXJYYwP2ZNQ1Hz9IWl6pzQnlY,9409
-ursa/agents/recall_agent.py,sha256=bQk7ZJtiO5pj89A50OBDzAJ4G2F7ZdsMwmKnp1WWR7g,813
-ursa/agents/websearch_agent.py,sha256=rCv4AWbqe5Us4FmuypM6jptri21nKoNg044ncsu9u3E,8014
-ursa/prompt_library/code_review_prompts.py,sha256=-HuhwW9W_p2LDn44bXLntxLADHCOyl-2KIXxRHto66w,2444
-ursa/prompt_library/execution_prompts.py,sha256=JBBmzVV0605uwFXNv0pxH0fXHqtmOgcDzabjpq3wt2A,2153
-ursa/prompt_library/hypothesizer_prompts.py,sha256=ieupOF5tUy_u8actOjPbK-y5Qkrgw6EYxAfw6RXBebs,762
-ursa/prompt_library/literature_prompts.py,sha256=zhBiN3Q-1Z2hp-hkXXp0T8Ipc-6YUM9gw85DjNu1F6I,421
-ursa/prompt_library/planning_prompts.py,sha256=C8IfVc3ny_5-03bJZop2Yax7wfqS_UIdUGsTZSNQRC0,3534
-ursa/prompt_library/websearch_prompts.py,sha256=n4DJaYn_lIYAVtdy00CCJjT-dLWhn2JNipYqMJAotdY,8846
-ursa/tools/run_command.py,sha256=sQRuHtRyJYWEyL9dpW_Ukc-xQ5vmKKJK1i_6z3uKEfA,690
-ursa/tools/write_code.py,sha256=DtCsUMZegYm0mk-HMPG5Zo3Ba1gbGfnXHsv1NZTdDs8,1220
-ursa/util/diff_renderer.py,sha256=1L1q2qWWb8gLhR532-LgJn2TrqXDx0gUpPVOWD_sqeU,4086
-ursa/util/memory_logger.py,sha256=GiKYbQBpxlNRLKyqKFJyrbSbVCkXpRB7Yr5so43tUAw,6097
-ursa/util/parse.py,sha256=M0cjyQWmjatxX4WbVmDRUiirTLyW-t_Aemlrlrsc5nA,2811
-ursa_ai-0.5.0.dist-info/licenses/LICENSE,sha256=4Vr6_u2zTHIUvYjoOBg9ztDbfpV3hyCFv3mTCS87gYU,1482
-ursa_ai-0.5.0.dist-info/METADATA,sha256=Um85Xzvs6LSGUg9X0tWitsLVwYqYgMJ0I3EhYzK8oIE,6898
-ursa_ai-0.5.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-ursa_ai-0.5.0.dist-info/top_level.txt,sha256=OjA1gRYSUAeiXGnpqPC8iOOGfcjFO1IlP848qMnYSdY,5
-ursa_ai-0.5.0.dist-info/RECORD,,