[devin-ai-integration]

Summary

Adds tig_cli.api so VICAR programs can be run from Python in the TIG container, with their output returned to the caller instead of streamed to the terminal:

from tig_cli import Tig

with Tig() as tig:                                  # same config/env/container as the `tig` command
    r = tig.run("gen", "test.vic", 64, 64)          # Result(tool='gen', exit_code=0, outputs=['/home/you/work/test.vic'])
    r.stdout, r.stderr, r.exit_code, r.ok
    tig.run("label", "-list", inp="test.vic").check()          # kwargs -> keyword=value; check() raises VicarError
    tig.marsxyz(inp=["l.vic", "r.vic"], out="xyz.vic")        # list -> inp=(l.vic,r.vic); tig.<tool> == tig.run("<tool>")
    tig.run("sh", "-c", "...", stdin=..., env={...}, timeout=30, workdir=other)

Design points that aren't obvious from the code:

• Reuses the CLI's machinery, not a new path. Tig wraps ContainerManager (config layering, image/runtime selection, mounts, calibration, claims, PathTranslator) and issues its own runtime exec -w <cwd> -e DISPLAY -e TIG_EXEC_ID … via subprocess.run(capture_output=True). It deliberately does not go through fast.run/dispatch, which are built around handing the tool the caller's terminal. A script and a shell therefore share one warm container, and tig --shutdown still applies.
• Files aren't copied back — they're already on the host. Since the home dir / cwd / writable paths are bind-mounted, outputs land on the host as the tool writes them. Result.outputs is computed by fingerprinting (mtime_ns, size) every path-like value in the arguments before and after the run (positional args, k=v values, (a,b) lists; flags skipped) and reporting the ones created or changed, as host Paths. Files a tool names on its own (e.g. marsmesh's .mtl) aren't listed but are in workdir.
• workdir is a Tig() setting, not os.getcwd(). build_mounts only mounts the process cwd rw, so Tig appends its workdir to writable_paths and translates it for exec -w.
• Non-zero exit is reported, not raised (VICAR programs frequently exit non-zero on success); check=True/.check() opt in to VicarError. timeout= kills the client and then the in-container process tree via kill_tree_command(TIG_EXEC_ID, SIGKILL), raising VicarTimeout with partial output.
• tig_cli/__init__.py exports Tig, Result, VicarError, VicarTimeout, run through a module __getattr__ so the CLI fast path doesn't pay for importing the API.

Tests: tests/test_api.py (49, offline, FakeRuntime + a scripted stand-in for subprocess.run that writes files so output tracking is exercised) and tests/integration/test_api.py (8, against the real image: gen → label → vicario pipeline, /host translation, stdin/env, timeout kill, container sharing across handles). Both pass locally; the full pytest -m "not integration" suite is green (467).

README: new "Python API" section in tig-cli/README.md, one-line mention in the root README.

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/477ff427de644f99bbf15a28107e6cf3
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/477ff427de644f99bbf15a28107e6cf3?variant=devin
Requested by: @HuiJun

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

---

Original prompt from jason.han

@JPL-Devin/tig Could we make a python api such that we could call vicar processes via python, have the commands actually run in our tig image and return the response or file back?