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

# minters

> *money maketh man*

`minters` is the packaged, local-first Mint distribution. It gives you the Seal terminal UI, a writable Mint workspace on your machine, the contract runner, the harness, the farm server, and the same repository structure the regulator expects when it reads, edits, validates, and runs contracts.

This README is written as a cookbook. Start at the quick start, then jump to the recipe that matches what you want to do.

## quick start

Install or upgrade the package:

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

Before you send your first prompt, make sure your local workspace or shell has a `NINETH_API_KEY` available. Seal uses Nineth for model requests, and without that key the UI can start but requests cannot run.

Example:

```bash
export NINETH_API_KEY=your_api_key_here
minters run
```

Launch the Seal UI:

```bash
minters run
```

On first launch, `minters` creates or reuses a writable Mint workspace, seeds it with the packaged project tree, and starts the interface defined in `regulator/seal.py`.

The packaged install is intentionally lean. It brings in the core dependencies needed for Seal and the local regulator runtime. Broker-specific tools stay optional and can be installed only when you need them.

## recipe 1: choose where your workspace lives

By default, `minters run` resolves the workspace in this order:

1. `--workspace /path/to/mint`
2. `MINTERS_WORKSPACE` or `MINT_WORKSPACE`
3. the current directory if it already looks like a Mint workspace
4. `~/.local/share/minters/workspace`

Use an explicit workspace when you want full control over where the model reads and writes files:

```bash
minters run --workspace ~/trading/mint
```

Ask `minters` which workspace it will use:

```bash
minters workspace
```

Or resolve a specific target without launching the UI:

```bash
minters workspace --workspace ~/trading/mint
```

If you want the model to operate on an existing checkout of this repository, open a shell in that checkout and run:

```bash
cd /path/to/mint
minters run
```

That keeps file edits, contracts, `.env`, and generated artifacts inside that same filesystem tree.

## recipe 2: launch Seal with a specific model

Override the default regulator model for a single session:

```bash
minters run --model 1984-m3-0421
```

Or make it your default for all sessions:

```bash
export REGULATOR_MODEL=1984-m3-0421
minters run
```

## recipe 3: understand what gets created on first launch

The first bootstrap copies the packaged Mint runtime into your workspace, including:

- `contracts/` for strategy files
- `harness/` for the contract runner and broker-facing APIs
- `farm/` for the local MT5 Farm server
- `regulator/` for the Seal UI and local service logic
- `buildfile/`, `testsuite/`, and the top-level project files

That means the model can inspect, create, modify, validate, and run contracts against the same workspace tree a human sees.

Your seeded workspace also gets a slim `requirements.txt` with the core runtime dependencies used by the packaged app. Install broker- or farm-specific extras only when your workflow needs them.

## recipe 4: use the Seal interface day to day

Once Seal is open, type tasks directly into the prompt area and submit with `Enter`, `Ctrl+Enter`, or `Ctrl+S`.

Useful built-in examples:

```text
inspect the contracts folder and summarize the strategies
fix the gold contract and iterate until it runs healthy
grep the repo for all uses of regulator and explain the flow
write a new contract in contracts/demo/contract.py and validate it
```

Useful local commands inside Seal:

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

The feed shows:

- your prompt block
- tool calls such as reads, searches, file edits, and contract runs
- success or failure observations for each local service action
- the final model response

## recipe 5: create a contract manually

Every runnable contract is just a Python file under `contracts/` with a class whose name ends in `Contract` and an `async def run(self)` method.

Example:

```python
import asyncio


class DemoContract:
    async def run(self) -> None:
        while True:
            print("demo heartbeat")
            await asyncio.sleep(5)
```

Save that as `contracts/demo/contract.py`, then ask Seal to validate or run it, or run it yourself from the workspace.

## recipe 6: run contracts from the workspace shell

From inside your Mint workspace, you can run a single contract file directly:

```bash
python contracts/demo/contract.py
```

Or run the contract discovery loop that continuously scans `contracts/` and restarts workers when files change:

```bash
python -m harness.bundler
```

The bundler injects `MINT_WORKSPACE`, and the runner loads your workspace `.env` before importing contract code.

## recipe 7: use the default local farm backend

The default operating mode is the local farm-backed flow.

Start the Farm server from the workspace:

```bash
python -m farm.main
```

Expected endpoints:

- API: `http://localhost:8000`
- Controller: `tcp://127.0.0.1:8888`

Quick status check:

```bash
curl http://localhost:8000/farm/status
```

Use this mode when your machine is hosting or controlling MT5 instances locally.

## recipe 8: switch to MetaAPI or farm_ext

Use the MetaAPI-backed external mode when you want cloud account access instead of the local farm:

```bash
export BROKER_MODE=farm_ext
export METAAPI_TOKEN=your_metaapi_token
export METAAPI_ACCOUNT_ID=your_metaapi_account_id
```

Then launch Seal or run your contracts as usual.

If you want Mint to choose automatically, use:

```bash
export BROKER_MODE=auto
```

## recipe 9: switch to Capital.com

Enable the Capital backend:

```bash
export BROKER_MODE=capital
```

Or:

```bash
export CAPITAL_ENABLED=true
```

Set credentials in your workspace `.env` or shell:

```bash
CAPITAL_API_KEY=your_api_key_here
CAPITAL_IDENTIFIER=your_email@example.com
CAPITAL_PASSWORD=your_password
CAPITAL_DEMO=true
```

If you need the Rust bridge locally, build it from the workspace:

```bash
cd harness/capital
maturin develop
```

Then start Seal again and let the model work against the Capital-enabled workspace.

## recipe 10: keep secrets local

`minters` does not need your broker credentials baked into the package. Keep them in one of these places on your own machine:

1. a workspace-local `.env`
2. exported shell environment variables
3. platform-specific secret storage used by your local runtime

Typical knobs you may set locally include:

- `NINETH_API_KEY`
- `BROKER_MODE`
- `METAAPI_TOKEN`
- `METAAPI_ACCOUNT_ID`
- `CAPITAL_API_KEY`
- `CAPITAL_IDENTIFIER`
- `CAPITAL_PASSWORD`
- `CAPITAL_DEMO`
- `REGULATOR_MODEL`

## recipe 11: upgrade minters safely

To get the latest package version:

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

Your existing workspace is not wiped. `minters` only seeds files that are missing, so your contracts, edits, and `.env` stay local.

## recipe 12: build and test the package locally

From the repository root:

```bash
python -m pytest testsuite/test_workspace.py -q
python -m build
```

Install the built wheel locally for a smoke test:

```bash
python -m pip install --force-reinstall --no-deps dist/minters-0.2.11-py3-none-any.whl
minters workspace --workspace /tmp/minters-smoke
```

## recipe 13: troubleshoot the common cases

If Seal opens but edits land in the wrong place:

```bash
minters workspace
```

Then relaunch with an explicit path:

```bash
minters run --workspace /path/to/your/mint
```

If a contract cannot import the runtime, make sure you are running inside a real Mint workspace that contains `harness/`, `contracts/`, and `regulator/`.

If Seal starts but every prompt fails immediately, check the model credentials first:

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

If that is empty, add `NINETH_API_KEY` to your workspace `.env` or export it before launching `minters run`.

If you see a client-library compatibility error mentioning `default_service`, upgrade the runtime package or the Nineth client:

```bash
pip install --upgrade minters 'nineth>=0.5.16'
```

If Capital mode fails with an import error for the Rust bridge, rebuild it:

```bash
cd harness/capital
maturin develop
```

If farm mode is selected but no local server is reachable, start the farm process first:

```bash
python -m farm.main
```

If you want the model to work on this repository itself instead of a seeded copy, launch `minters run` from the repository root or set `MINTERS_WORKSPACE` to that path before starting Seal.
