Metadata-Version: 2.4
Name: node-mantis
Version: 0.1.0a10
Summary: NodeMantis Python configuration, browser setup, and installation validation tools
Author: NodeMantis
License-Expression: LicenseRef-NodeMantis-Proprietary
Project-URL: Homepage, https://github.com/Node-Mantis/CleanSlate#readme
Project-URL: Repository, https://github.com/Node-Mantis/CleanSlate
Project-URL: Issues, https://github.com/Node-Mantis/CleanSlate/issues
Keywords: browser,automation,playwright,node-mantis,nodemantis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Provides-Extra: browser
Requires-Dist: playwright>=1.59.1; extra == "browser"
Dynamic: license-file

# NodeMantis Python

The NodeMantis Python SDK: browser-driving agent sessions at parity with the
npm `node-mantis` package, plus configuration, browser setup, and installation
validation tools.

Platform wheels bundle the same compiled native runtime the npm SDK uses; the
Python layer is a thin client that spawns it and forwards requests. Browser
sessions additionally need Playwright for Python (the `[browser]` extra) — the
runtime launches and drives a real Google Chrome through it.

Customer install:

```bash
pip install "node-mantis[browser]"
python -m nodemantis configure --api-key "$NODEMANTIS_API_KEY"
python -m nodemantis install-browser --browser chrome
python -m nodemantis smoke
```

Run a browser goal:

```python
from nodemantis import NodeMantis

with NodeMantis.start(start_url="https://example.com", headless=True) as mantis:
    result = mantis.run("Open the More information link.", max_iterations=5)
    print(result.ok, result.reason)
```

The session surface mirrors the TypeScript SDK: `NodeMantis.start()` /
`NodeMantis.preflight()`, and per-session `go`, `run`, `step`, `retrieve`,
`extract`, `check`, `close` (sessions are context managers). Options are
snake_case (`max_iterations`, `screenshot_enabled`, `result_schema`,
`allow_navigation`, …); `model` selects a size tier (`"small"`, `"standard"`,
`"large"`). `run`/`step` accept an `on_progress` callback for per-iteration
narration; callbacks arrive on a background thread and must not call session
methods. `retrieve` returns a discriminated result (`status` of `success`,
`not_found`, or `error`, with `data`, `contributor_ids`, `warnings`, `tokens`,
`final_url`). Schemas are plain JSON Schema dicts (pydantic v2 model classes
are also accepted). `attach()` and `context_options` are TypeScript-only.

API keys resolve from the `api_key` argument, then `NODEMANTIS_API_KEY`,
`NODEMANTIS_AUTH_TOKEN`, and finally the `nodemantis configure` config file.
The package always connects to the hosted Node Mantis API; the service
endpoint is not customer-configurable.

`node-mantis[browser]` installs Playwright for browser sessions, checks, and
smoke tests. Browser binaries are installed separately; run
`python -m nodemantis install-browser --browser chrome` for Google Chrome or
use `--browser chromium` for Playwright Chromium.

Installing the wheel also puts a `nodemantis` command on `PATH` (equivalent to
`python -m nodemantis`); `pipx install node-mantis` gives the same command in
an isolated environment. This CLI covers setup verbs only — `configure`,
`doctor`, `install-browser`, `smoke`. Command-line task execution
(`nodemantis run`, `nodemantis retrieve`) ships with the npm package:
`npm install -g node-mantis`. If both are installed, whichever is first on
`PATH` wins; the setup verbs behave identically.

Validate API access, credentials, and the selected browser from Python:

```python
from nodemantis import preflight

report = preflight(check_browser_launch=True, timeout_seconds=5)
if not report.ok:
    raise RuntimeError(report.checks)
```

Supported alpha platforms: Linux x64, Windows x64, macOS x64, and macOS arm64.
Wheels without a bundled runtime (source-free builds) raise
`RUNTIME_NOT_INSTALLED` when starting a session; advanced setups can point
`NODEMANTIS_RUNTIME_PATH` at a runtime executable.

This package is proprietary alpha software. Use is governed by `LICENSE.txt`
and applicable NodeMantis terms.
