Metadata-Version: 2.4
Name: minters
Version: 0.3.3
Summary: money maketh man.
Author-email: Oyebamijo <boy@oyebamijo.com>
Project-URL: Homepage, https://github.com/oyebamijo/mint
Project-URL: Bug Tracker, https://github.com/oyebamijo/mint/issues
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: python-dotenv==1.0.0
Requires-Dist: textual<9,>=8.2.5
Requires-Dist: nineth>=0.5.16

# minters

> money maketh man

`minters` is now a remote-first Mint client.

The human machine gets a thin local install: the Seal terminal UI, the model connector, and the remote workspace client.
The actual Mint workspace, repository CRUD, validation, contract execution, and shell sandboxing live on Modal.

The default deployed backend URL is:

```text
https://weirdpablo--minter-api.modal.run
```

That URL is handled in code. A normal client does not need to set it manually.

This README is written as a cookbook. Start at the quick start, then jump to the recipe you need.

## quick start

Install or upgrade the thin client:

```bash
pip install --upgrade minters
```

Launch Seal:

```bash
minters run
```

On first launch, Seal opens a short setup wizard. In the remote-first path it only asks for:

- your `NINETH_API_KEY` for model requests on the local machine
- the broker or harness credentials that should be synced into the remote Modal workspace

The client does not need a local copy of the Mint repository anymore.

If you want to skip the wizard and use the saved local settings immediately:

```bash
minters run --default
```

## recipe 1: understand the new architecture

There are now two sides.

Client side:

- `minters run`
- the Textual Seal UI
- the Nineth client configuration
- the HTTP connector that talks to Modal

Server side on Modal:

- the writable Mint workspace volume
- repository file reads and writes
- grep, tree, and validation helpers
- contract execution
- short-lived shell sandboxes
- broker and harness runtime credentials

That means the model works against the server-side workspace instead of pushing the full source tree down to every client machine.

## recipe 2: set credentials as a client

Run:

```bash
minters run
```

The wizard will:

1. ask for `NINETH_API_KEY` and store it locally so the UI can call the model
2. ask which remote credential profile you want to update
3. send those broker or harness credentials to the Modal workspace `.env`

Examples of values that may be synced to the remote workspace:

- `FARM_HOST`
- `MASTER_ACCOUNT_ID`
- `METAAPI_TOKEN`
- `METAAPI_ACCOUNT_ID`
- `CAPITAL_API_KEY`
- `CAPITAL_IDENTIFIER`
- `CAPITAL_PASSWORD`
- `CAPITAL_DEMO`

## recipe 3: see where Seal is running

Inside Seal, use:

```text
/target
```

That prints the active target. In the normal packaged flow it should point at the deployed Modal workspace, not the local machine.

Useful interactive commands:

```text
/help
/clear
/model 1984-m3-0421
/target
```

## recipe 4: keep the client machine thin

The packaged client no longer bootstraps the full repository into the user workspace by default.

The default workspace path is still used for local config files:

```bash
minters workspace
```

But the repository itself stays on Modal unless a maintainer explicitly forces local development mode.

## recipe 5: force local mode for development

If you are working inside this repository and want the old local execution path for debugging, use:

```bash
minters run --local
```

Or:

```bash
export MINTERS_FORCE_LOCAL=true
minters run
```

If you also want the old local workspace tree to be copied into a target directory, opt in explicitly:

```bash
export MINTERS_ENABLE_LOCAL_WORKSPACE_BOOTSTRAP=true
minters run --local --workspace /tmp/mint-local
```

That path is for maintainers and local debugging, not for normal client installs.

## recipe 6: deploy the backend to Modal

From the repository root:

```bash
modal deploy entry.py
```

The deployed web endpoint is created from `entry.py`, which serves the Modal-backed FastAPI app.
The backend mounts the named Modal volume `minter`, keeps the workspace under `/data/minter/workspace`, and runs command or contract execution in short-lived Modal sandboxes.

The deployment output includes the public URL. In the current deployment it is:

```text
https://weirdpablo--minter-api.modal.run
```

That value is baked into the client connector as the default remote URL.

## recipe 7: smoke test the deployed backend

After deployment, run:

```bash
python buildfile/modal_smoke.py --url https://weirdpablo--minter-api.modal.run
```

The smoke script checks:

- `/modal/health`
- `/modal/workspace/info`
- remote `read_file`
- remote `write_file`
- remote `sandbox_run`

The CI pipeline now runs that same smoke step after `modal deploy entry.py`.

## recipe 8: understand what ships to PyPI

The PyPI package is now intentionally thin.

It ships:

- `minters`
- the client-facing `regulator` modules used by Seal
- the remote connector

It does not ship the full repository runtime to end users by default.

That means the client wheel no longer bundles:

- `harness/`
- `farm/`
- `contracts/`
- `testsuite/`
- the Modal server module used only by deployment
- the old native Capital wheel payload in the client package

## recipe 9: understand CI/CD now

The release workflow now does four things:

1. bumps and tags the version when the commit message starts with `build:`, `feat:`, or `chore:`
2. builds the thin client wheel once
3. verifies client install on Linux, macOS, and Windows
4. deploys the Modal backend, parses the deployed URL, and runs the live smoke script

That gives you a thin cross-platform client plus a single deployed backend runtime.

## recipe 10: troubleshoot the common cases

If Seal starts but cannot reach the backend, check the deployed service URL first:

```bash
python - <<'PY'
from regulator.remote import remote_url
print(remote_url())
PY
```

If the wizard fails while syncing broker credentials, the Modal deployment is reachable but the remote workspace API rejected the write. Redeploy the backend and rerun:

```bash
modal deploy entry.py
python buildfile/modal_smoke.py --url https://weirdpablo--minter-api.modal.run
```

If you intentionally need the old local path, use `minters run --local`.

If model requests fail immediately, verify the local model credential:

```bash
echo "$NINETH_API_KEY"
```

If that is empty, add `NINETH_API_KEY` locally and rerun `minters run`.
