Metadata-Version: 2.4
Name: furb-monty
Version: 0.3.4
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Dist: furb==0.3.4
Summary: furb for python, with the engine in monty: every name of engine.pyi, over one life in the sandbox.
Author-email: Abel Lucas <uaelucas@gmail.com>
License-Expression: AGPL-3.0-only
Requires-Python: >=3.14
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Issues, https://github.com/uael/furb/issues
Project-URL: Source, https://github.com/uael/furb

# furb-monty

The engine of furb for Python, run in monty, a Python interpreter written in Rust. Most programs do not import it
directly: `pip install furb` installs it, and `furb.open` opens a life on it, as
[the examples](https://github.com/uael/furb/blob/main/docs/examples/README.md) show. Read on when you write a host of
your own, which boots an engine on ears that you choose.

## What it gives

- `furb_monty.engine` gives every name of the contract,
  [`engine.pyi`](https://github.com/uael/furb/blob/main/src/furb/engine.pyi), over one life of the engine in the
  sandbox of monty. The crate loads the Kernel there, so this package needs none of its own.
- `furb_monty.gate` is the gate of the crate. The package `furb` reads a word with it too.
- `furb_monty._monty` is the door itself. It gives the same host API as the package of TypeScript, each name in the
  case of Python. Its `Engine` has one method for each verb of the contract, which takes the words that the verb
  needs by position and the others by name, and gives an `Act` when the verb makes one.

`FURB_ENGINE=monty` makes `from furb import engine` give `furb_monty.engine`. The suite of furb runs on both engines.

## Open a life

`_monty.opened(directory=..., record=...)` opens a life as every host of the crate opens one. It gives the record and
the ears of the crate, which the host boots after its own ears. `Engine.open(ears, directory=...)` boots them at
once.

```python
from furb_monty import _monty, engine

record, ears = _monty.opened(directory=".", record="life.jsonl", actor="anthropic:claude-opus-5-5")
# `world` is an ear of the host that answers the rest, a prompt to the operator among it.
root = engine.boot(record, world=world, **dict(ears))
```

The ears of the crate are the provider of the models, the extensions, the ear of each official extension, the files, the
commands, time, and the store and the log when the life keeps its record. The extensions enable at the start what the
configs of the user and of the directory turn on, unless `extensions=False`. Each ear is a `NativeEar`, which
`furb_monty.engine.boot` takes beside the generators of this interpreter, and which the engine of this interpreter,
`furb.python`, steps as a generator of its own.

The words of `opened`, each of which can be left out:

- `actor` is the default actor, and `roster` the models that the provider offers beside it. With no roster, it
  offers each model of the catalog, and with neither, the first of them is the default actor. A roster that names no
  model offers the model of the actor alone, and with no actor, the operator alone.
  [Models](https://github.com/uael/furb/blob/main/docs/models.md) says how a model is named.
- `keeps` false keeps nothing in the record, and `inspecting` true opens a life that keeps nothing, enables nothing
  new, and asks no model.
- `extensions` false enables no new extension, and `config` names the config directory of the user.
- `snapshot` false opens the life with a replay of its record, and keeps no snapshot of it.
- `answer`, a function, answers each request in place of the models, as the suite of furb does.
- `stream`, a function, hears what a model writes as it writes it, and `retrying` each retry of a call of a model.
- `log`, a function, hears each report of the life that no model reads, one line each, in place of the stderr of the
  process.
- `claude` names the claude command line to run, and `stall` how many seconds a turn of it may go with no progress.
- `images` is the directory of the images that a message names.

Only the opening of a life makes the files of a record again in its scratch directory, and gives a life with no record
a directory that goes with it. `scratch(record)` gives the scratch directory of a record, which a host removes when it
deletes the record.

## The parts one by one

- `models(claude)` gives the models that the catalog of this machine offers, `model(name)` one model by its name, and
  `levels()` the levels of effort.
- `files(scratch)`, `bash(scratch, record)`, `time()`, `extensions(given)`, `memory(config)` and `skills(config)`
  give the ears one by one, as the suite of each extension boots them. `store(path)` gives the record that a path
  holds and the ear of its store, and `official()` gives the official extensions, which `extensions` takes. The files
  and the commands share the scratch directory that the host names, which a word reads as `scratch://` and a command
  as `$TMPDIR`.
- `answered(shape, line)` reads a line of the operator as a value of one of the `shapes()`, by the rules that every
  console of the crate reads a line by.
- `_monty.SYSTEM` is the system prompt of every model: the engine, minified with its program kept as it is.
- `setup()` says what a first run checks of each place of the models, `parts(project)` gives the part for the TUI of
  each extension, `enabled(root)` the extensions that a record enabled, and `kept(path)` the entries of a record.
  `furb_monty/_monty.pyi` gives each other name, with its types.

## Work that waits

- `furb_monty.engine.pending()` names each act that an earlier life left and that waits for a wake, as
  `("bash1", "bash")`.
- `furb_monty.engine.parked()` names each run of a word or reply that a crash loop parked, which a wake does not run.
- `furb_monty.engine.retry(id)` runs a parked act again.

[A resumed life](https://github.com/uael/furb/blob/main/docs/rpc.md#a-resumed-life) says which acts each one names.

## Make an act once

`furb_monty.engine.keyed(key, kind, *args, **kwargs)` makes the act of a verb once for a key of the client, across a
crash of the host and a retry of the client, as `keyed("k1", "prompt", int, "count the lines", on=root)`. A key fact
goes to the record before the act, and a later call with the same key on the same chain gives the act that the key
made, in this life or in a later life on the record. When the host crashed after it kept the key and before it kept
the act, the call makes the act.

## Ears of this interpreter

`boot` takes a generator of this interpreter as an ear, beside the ears of the crate. A verb that it calls while it
hears goes to the life that it hears.

