Metadata-Version: 2.4
Name: nga
Version: 0.3.0
Summary: Local-first agentic browser automation factory
Project-URL: Homepage, https://github.com/omerlefaruk/nga
Project-URL: Repository, https://github.com/omerlefaruk/nga
Project-URL: Issues, https://github.com/omerlefaruk/nga/issues
Author: nga maintainers
License: MIT
Keywords: automation,browser,factory,local-first,rpa
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Requires-Python: >=3.11
Requires-Dist: flask<4,>=3.0
Requires-Dist: playwright<2,>=1.54
Requires-Dist: tomli-w<2,>=1.0
Requires-Dist: waitress<4,>=3.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# nga

Local-first agentic browser automation factory. This repository bootstraps the
installed Factory: a pip-installable Python package that starts a local Control
Room on a random loopback address and reports application and database health.

This is the first milestone of the Dark Factory MVP (spec: issue #1, ticket:
issue #2). Per-user state lives in SQLite under `%USERPROFILE%\.nga` and never
inside Git.

## Requirements

- A supported Python installation (3.11 or newer) on Windows.
- An internet connection for the initial `pip install` of dependencies.

## Install

After the package is published to PyPI, install it on a clean Windows user
account:

```powershell
py -3.11 -m pip install nga
nga install-skills
```

This installs the `nga` command and its Python dependencies into the active
environment. The second command installs `nga-init` and `vendor-delivery` in
`%USERPROFILE%\.agents\skills` for all compatible agents on that user account.

For a local checkout, use:

```powershell
py -3.11 -m pip install .
nga install-skills
```

Playwright's Python package is installed as a dependency. If the customer PC
does not have Chrome or Edge, install the managed Chromium browser once:

```powershell
py -3.11 -m playwright install chromium
```

## Start the Factory

```powershell
nga serve
```

The Factory:

- starts the Control Room and reports a **random loopback address**, for
  example `Control Room: http://127.0.0.1:52341/ (loopback only)`;
- never binds to a LAN address;
- opens the reported address in the default browser (pass `--no-open` to
  suppress this);
- creates the per-user SQLite database at `%USERPROFILE%\.nga\state.db` on
  first start and keeps it valid across restarts.

Set `NGA_HOME` to redirect per-user state to another directory:

```powershell
$env:NGA_HOME = "C:\path\to\state"; nga serve
```

The health view at `http://127.0.0.1:<port>/` shows the running application
version and the local database health.

## Start an automation project

Open an empty project folder and invoke `$nga-init`. The project stays in that
folder. It uses `src`, `tests`, `config`, `docs`, `data/input`, `data/output`,
and a hidden `.nga` control directory.

## Release the package

Build and validate a wheel from the repository root:

```powershell
py -3.11 -m pip install build twine
py -3.11 -m build
py -3.11 -m twine check dist\*
```

For the normal release path, create a GitHub Release. The repository's
`publish.yml` workflow then builds and publishes the distributions with PyPI
Trusted Publishing.

For a manual upload, run this only after the package has passed the checks:

```powershell
py -3.11 -m twine upload dist\*
```

## Focused tests

Fast startup and health behavior (no network required):

```powershell
py -m pytest tests/test_state.py tests/test_control_room.py -v
```

Clean pip-install proof on an isolated venv (requires network to download
dependencies, takes a few minutes):

```powershell
py -m pytest tests/test_pip_install.py -m pip_install -v
```

Development environment (optional):

```powershell
uv venv --python 3.11
uv pip install -p .venv -e ".[dev]"
.venv\Scripts\python -m pytest
```
