Metadata-Version: 2.4
Name: minters
Version: 0.4.1
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
```
hello, please can you do a thorough research on the current state of the world as regards the finance and then do some research on gold to find key important details about the asset.. then develop a dependency tree of all the nodes in the gold supply chain.. write the result of your research in a about.md file which you'll create in the `contracts/gold/` subdirectory... then the dependency graph should be a json and you should include it in the same path but with a name ` dep.json`.

Useful local commands inside Seal:

```text
/help
/clear
/model 1984-m3-0421
/telemetry
/handoff contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/stop-run RUN_ID
```

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 `MINT_BUNDLER`, and the runner loads your workspace `.env` before importing contract code.

That matters for autonomous contracts such as `contracts/con-05-13-26/contract.py`: when they see `MINT_BUNDLER=1`, they can stay in a guarded loop instead of doing a single research pass and exiting.

## 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: hand off an autonomous contract to Modal

Deploy the current API entrypoint first:

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

The deployed API keeps managed contract state under the named Modal volume `minter-state`, mounted at `/data/minter`, so remote runs can be resumed after container restarts.

Point Seal and the model at that deployment:

```bash
export MINTERS_REMOTE_URL=https://your-modal-endpoint.modal.run
```

Useful Seal commands for the remote runtime:

```text
/handoff contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
/telemetry
/telemetry RUN_ID
/stop-run RUN_ID
```

The `con-05-13-26` contract now supports a guarded autonomous loop. The most important knobs are:

- `CON051326_AUTONOMOUS=true` to keep the contract cycling
- `CON051326_ENABLE_LIVE=true` to allow real order submission
- `CON051326_CONFIRM_BARS=3` for multi-bar confirmation
- `CON051326_MIN_PAIR_SCORE=3.0` to require a stronger selected pair
- `CON051326_MIN_CONFIDENCE=0.60` to require stronger model conviction
- `CON051326_MAX_DAILY_LOSS_PCT=0.02` to stop live trading after a daily drawdown breach
- `CON051326_STOP_ON_DAILY_LOSS=true` to exit the loop when the daily loss guard trips
- `CON051326_FORWARD_BROKER_ENV=true` to let contract-driven self-handoff forward the allowlisted Capital credentials into the remote worker
- `CON051326_REMOTE_ENV_KEYS=...` to tune exactly which broker-related variables may be forwarded during self-handoff or `/handoff-live`

Use `/handoff` when the deployed remote runtime already has the credentials and contract env it needs.

Use `/handoff-live` when your local workspace `.env` is the source of truth for the live Capital credentials or the current `CON051326_*` runtime knobs. That command forwards the local `CON051326_*` settings, forces `CON051326_REMOTE_HANDOFF=0` in the remote worker to prevent nested handoffs, and forwards only the broker env names in the allowlist.

The runtime exposes these over the API as:

- `GET /terminal/contracts/runs`
- `GET /terminal/contracts/runs/{run_id}`
- `POST /terminal/contracts/handoff`
- `DELETE /terminal/contracts/runs/{run_id}`
- `GET /terminal/telemetry?run_id=...`

The regulator model can use the same remote surfaces through the local services `remote_contract_runs`, `remote_contract_run`, `remote_contract_handoff`, `remote_contract_stop`, and `remote_contract_telemetry`.

## deep dive: full contract design lifecycle

This section is intentionally pedantic. It describes the full working loop from the first line of a new strategy to a managed remote handoff that you can observe and stop safely.

### 1. Decide the contract boundary before you write code

Every runnable strategy in Mint is a file under `contracts/` containing a class whose name ends with `Contract` and exposes `async def run(self)`.

The smallest valid shape is:

```python
import asyncio


class ExampleContract:
    async def run(self) -> None:
        print("hello from mint")


if __name__ == "__main__":
    asyncio.run(ExampleContract().run())
```

Choose the contract directory first. A practical layout looks like this:

```text
contracts/my_strategy/
  contract.py
  about.md
  policy.md
  report.md
  bench/
    test_contract.py
```

Use `about.md` for research and market context, `policy.md` for guardrails and execution rules, `report.md` for generated findings, and `bench/` for contract-specific tests or replay fixtures. The runtime only requires `contract.py`, but the extra files are what keep a trading strategy understandable after the first draft.

### 2. Pick the backend explicitly

When you already know the target broker, prefer the explicit engine handles:

```python
from harness import capital
from harness import farm
from harness import farm_ext
```

This avoids ambiguity about which backend a contract is written for. `capital` is the clearest path for Capital.com workflows. `farm` is for the self-hosted MT5 controller. `farm_ext` is for MetaAPI-backed MT5.

If the contract must switch brokers by environment, use the generic root-level dispatcher helpers instead, but do that on purpose. Do not accidentally mix broker-specific assumptions with the generic dispatcher surface.

### 3. Define the env contract as part of the strategy design

Before adding trading logic, decide which knobs must be adjustable without editing code. In practice that means environment variables.

For example, the `con-05-13-26` contract uses knobs such as:

- `CON051326_AUTONOMOUS`
- `CON051326_ENABLE_LIVE`
- `CON051326_CONFIRM_BARS`
- `CON051326_MIN_PAIR_SCORE`
- `CON051326_MIN_CONFIDENCE`
- `CON051326_MAX_DAILY_LOSS_PCT`
- `CON051326_STOP_ON_DAILY_LOSS`

Design these variables early and keep the naming consistent. A good pattern is one stable prefix per contract. That gives you three benefits:

1. You can tune behavior from `.env` without patching the strategy.
2. You can forward a small, intentional set of values during remote handoff.
3. You can understand the live runtime state by reading the env contract, not reverse-engineering the code.

### 4. Separate research, selection, guards, and execution

The most maintainable Mint contracts do not mix every decision into one block. Treat the strategy as four stages:

1. Research: gather candles, macro context, watchlists, sentiment, or market metadata.
2. Selection: rank assets, pairs, or setups and decide which candidate is best.
3. Guards: apply risk checks, exposure checks, schedule checks, and kill-switch conditions.
4. Execution: place, modify, or skip orders based on the previous stages.

That separation matters because the same contract may run in three different modes:

1. research-only
2. paper-guarded but not live
3. live execution enabled

If research and execution are tightly coupled, it becomes much harder to run safe dry runs locally or remotely.

### 5. Emit artifacts and telemetry deliberately

Do not rely on stdout alone. A contract should leave behind artifacts that explain what it decided.

Good outputs include:

- a latest run artifact such as `latest_contract_run.json`
- state files for autonomous loops
- cached research inputs such as macro snapshots
- structured telemetry with a `run_id` when running under the managed runtime

This is what lets you answer questions later like "why was no trade submitted?" or "which guard blocked the order?" without rerunning the strategy under a debugger.

### 6. Run the contract directly first

Before you hand a strategy to the bundler or to Modal, run it in the narrowest possible way:

```bash
python harness/_runner.py contracts/my_strategy/contract.py MyStrategyContract
```

That path matters because `harness/_runner.py` is the real contract entry surface used by the managed runtime. It adds the workspace root to `sys.path`, loads the workspace `.env`, imports the target file, looks up the class name, and executes `asyncio.run(cls().run())`.

If the contract cannot survive the runner, it is not ready for bundler discovery or remote handoff.

### 7. Add tests at two levels

A complete strategy usually needs both root-level tests and contract-local tests.

Root-level `testsuite/` tests are for integration points such as:

- router behavior
- remote runtime registration
- env forwarding
- bundler restart and handoff control
- model-visible local services

Contract-local `bench/` tests are for strategy behavior such as:

- scoring logic
- risk guards
- portfolio selection
- macro overlays
- replaying canned price histories

Use the lightest command that proves the slice you changed:

```bash
pytest testsuite/test_my_feature.py -q
pytest contracts/my_strategy/bench/test_contract.py -q
```

If the contract has autonomous behavior, add tests for both the single-pass path and the loop path. That distinction is where a lot of trading regressions hide.

### 8. Exercise local deployment before remote deployment

In Mint, "local deployment" usually means one of two things:

1. running the contract directly through `harness/_runner.py`
2. letting the bundler discover and supervise it

To run the whole contract set together:

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

The bundler scans `contracts/`, launches matching contract classes through the runner, and keeps rescanning for changes. This is the correct environment for contracts that are supposed to stay alive, emit telemetry repeatedly, or react to file changes during iteration.

If your strategy depends on the farm backend, start the local farm service as part of local deployment:

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

If your strategy depends on Capital, make sure the bridge imports locally and the Capital credentials are present in `.env` or the shell.

### 9. Package or deploy the runtime only after the contract is stable locally

The remote runtime is not a substitute for local validation. Use remote handoff after these are already true:

1. the contract imports cleanly
2. the runner path works
3. the narrow tests pass
4. the contract writes sensible artifacts locally
5. you know which env vars must exist remotely

When you are ready, deploy the API:

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

Then point the local workspace at the deployed runtime:

```bash
export MINTERS_REMOTE_URL=https://your-modal-endpoint.modal.run
```

### 10. Choose the right handoff path

There are now three distinct handoff patterns in this repository.

Pattern 1: plain manual handoff

```text
/handoff contracts/my_strategy/contract.py MyStrategyContract
```

Use this when the remote runtime already has the required credentials and runtime knobs.

Pattern 2: live manual handoff with local env forwarding

```text
/handoff-live contracts/con-05-13-26/contract.py RiskAdjustedCapitalContract
```

Use this when your local workspace `.env` is the authoritative source for the live Capital credentials or for the current `CON051326_*` runtime settings. This command forwards the current local `CON051326_*` values, excludes path-specific state keys that should not be copied blindly, forces `CON051326_REMOTE_HANDOFF=0` in the remote worker so it will not recurse into another handoff, and forwards only the allowlisted broker variables.

Pattern 3: contract-driven self-handoff

Set the contract knobs in `.env`, including:

```env
CON051326_REMOTE_HANDOFF=1
CON051326_FORWARD_BROKER_ENV=1
CON051326_REMOTE_ENV_KEYS=CAPITAL_API_KEY,CAPITAL_IDENTIFIER,CAPITAL_PASSWORD,CAPITAL_DEMO,CAPITAL_BASE_URL,CAPITAL_DEMO_URL
```

Use this when the contract itself decides to move into the remote runtime. The contract will forward the allowlisted broker vars automatically when `CON051326_FORWARD_BROKER_ENV=1`.

### 11. Observe the remote run instead of guessing

After handoff, always inspect the managed run and the telemetry.

Inside Seal:

```text
/telemetry
/telemetry RUN_ID
/stop-run RUN_ID
```

Over HTTP:

```text
GET /terminal/contracts/runs
GET /terminal/contracts/runs/{run_id}
GET /terminal/telemetry?run_id=...
DELETE /terminal/contracts/runs/{run_id}
```

The remote run record tells you the current status, the latest structured payload, and whether the process failed, completed, or is still running. The telemetry stream tells you why.

### 12. Iterate by changing the smallest surface that explains the failure

A disciplined Mint workflow looks like this:

1. inspect the latest artifact or telemetry
2. identify the exact failing surface
3. patch the smallest responsible code path
4. rerun the narrowest test or runner command
5. only then promote the change back through the bundler or the remote runtime

Do not use the remote runtime as the first place you discover basic import, env, or guard logic errors. Use it after the local lifecycle is healthy.

## recipe 11: 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`
- `MINTERS_REMOTE_URL`

## recipe 12: 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 13: build and test the package locally

From the repository root:

```bash
python -m pytest testsuite/test_workspace.py -q
python -m pytest testsuite/test_bundler.py testsuite/test_runtime_control.py testsuite/test_router_managed_contracts.py testsuite/test_regulator_remote_services.py testsuite/test_con_05_13_26_autonomy.py -q
python -m pytest contracts/con-05-13-26/bench/test_contract.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 14: 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 `/telemetry` or `/handoff` fails inside Seal, verify the remote runtime endpoint first:

```bash
echo "$MINTERS_REMOTE_URL"
curl "$MINTERS_REMOTE_URL/terminal/contracts/runs"
```

If a remote handoff succeeds but you do not see trades, inspect the guard state from telemetry. The autonomous contract blocks live submission when pair-score, confidence, macro alignment, multi-bar confirmation, or daily loss thresholds are not satisfied.

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.
