Metadata-Version: 2.4
Name: manifold-ai
Version: 2.20.1
Summary: Manifold: nodes publish one value each; agents read it as text, people see it as a picture; your machines share it.
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Manifold-agents/manifold
Project-URL: Repository, https://github.com/Manifold-agents/manifold
Project-URL: Issues, https://github.com/Manifold-agents/manifold/issues
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Environment :: Console
Classifier: Environment :: Web Environment
Classifier: Topic :: Software Development :: Libraries
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jsonschema>=4.18
Requires-Dist: starlette>=0.37
Requires-Dist: uvicorn>=0.29
Requires-Dist: keyring>=24
Requires-Dist: iroh>=1.1
Requires-Dist: certifi>=2024.2
Requires-Dist: websockets>=13
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: httpx2; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Dynamic: license-file

# Manifold

Manifold runs live nodes on your Mac and shows them to people and agents at once. Each node publishes one value.
People see it as a card on a canvas. Agents read it as text and press its actions from the command line. A manifold
is a set of nodes arranged for a purpose: a trading desk, a research queue, a household.

It runs on your machine with your accounts. Other machines join by invitation and see what you grant them. No one's
code runs on anyone else's machine.

This release is for **macOS**. Apple silicon gets the Rust door; Intel Macs run the Python door. Python 3.11 or newer.

## Install

```bash
uv tool install manifold-ai
```

This installs the `manifold` command on its own, fetching Python 3.13 if your Mac has nothing new enough. `uv` is
`brew install uv`. With Python 3.11 or newer already installed, `pip install manifold-ai` or `pipx install
manifold-ai` do the same. A Mac's built-in `python3` is 3.9, which is too old.

`manifold update` installs the newest release the way you installed it and restarts the core; `manifold update --check` only says
whether there is one.

## First minute

```bash
manifold
```

On a machine with no manifold yet this makes the **Desk** and opens it: a Brief, Questions and Findings, a Team, the
guide every agent reads, and two residents already at work — an always-on scout and an editor. Ask on the Questions card;
the scout works the question through to findings and the editor keeps the Brief. Shipped library types that reach only
keyless public sources run without a yes each (`approve auto on`, which the Desk sets); a key, a program or a drafted type
still waits for you.

## First manifold

```bash
manifold                         # the canvas, in your browser; the first time, it installs the core to run at login
manifold new desk --purpose "where the market stands" --section Market
```

`manifold` on its own always lands on the canvas, starting the core if it is not running. Seeing anything else means
something failed, and the line says what. `manifold -h` is the help.

Place nodes from the library, a thousand node types in a hundred domains. `manifold library` lists the domains,
`manifold library stocks` one domain's types, `manifold library weather` whatever matches a word; the canvas shows
them as a gallery.

```bash
manifold -m desk place stocks/quote Market symbol=^GSPC name="S&P 500"
manifold -m desk approve quote   # a type that reaches outside through a tool runs once you approve it
manifold -m desk ls              # what an agent reads: every card's headline values
manifold -m desk cat quote       # one card in full
```

A node that needs a key asks for it by name. `manifold key add` stores it in the macOS keychain, and it goes only
to the tool you approved it for.

## Agents

Any agent with a shell works a manifold through the same commands a person uses. One run of Claude Code or Codex
with Manifold as its tool:

```bash
manifold -m desk agent "say where the S&P stands and whether volatility is high" --can act
```

Agents that live in a manifold, with a standing task and a schedule: `manifold -m desk agents new …`. An agent runs
only on its own machine, on your own sign-in. No machine starts an agent on another.

An agent that may start agents here (`--can agents`) hands a longer making to the builder with `build "<what the node
should answer>"`: a builder agent starts on this machine, drafts the type (and a tool when one is needed), the Builder
card shows its progress, and you accept the draft. The voice, a Claude Code or Codex session and a resident all use that
one line.

An agent is told of nodes, sections and what each answers, never of the canvas: it adds a node with
`add <type> <section> …` and the card appears; it reads one group with `ls <section>` and `cat <section>`, so a task of
fifty nodes reads its own section, not the manifold. `place` is the same verb, the person's word.

An agent's learning outlives its run through the `memory` node (`manifold add agents/memory Knowledge`): one fact
per line, with where it came from and the day, written with `do remember`, revised or forgotten by id, read by the
next agent on any machine the section is shared with. It is a node like any other, so grants and feeds apply to it.

A fast, typed judgment — a probability, a pick, a grade — comes from a System One model through the `systemone` tool
and the `judge` node (`manifold add agents/judge Knowledge`). Set the tool up once on a machine: `manifold key add
TYPESAFE_API_KEY` for TypeSafe's jev, or `manifold tool set systemone provider=local url=…` for a model on this machine,
or `provider=custom` for any host that speaks the System One shape. Then any agent asks `do judge ask state=… question=…`,
and every judgment is logged on the node with what it cost.

## Working from Codex or Claude Code

Give the harness Manifold as a tool, not the raw command line:

```bash
codex mcp add manifold -- manifold mcp -m desk --can act,place,arrange     # one manifold
claude mcp add manifold -- manifold mcp -m all --can act,place,arrange     # any manifold here: the tool takes `manifold` with each command
```

Each session is one run with that grant: it shows on the Agents card as `codex · session`, every command it sends is in
the activity feed, and the tool refuses whatever the grant does not cover. Approving, keys, members and the canvas stay
yours, in your own terminal or in the browser. A shell inside a harness that runs `manifold` directly can read, and is
told to use the tool for the rest. When you ask the agent to show you the canvas, its `canvas` command opens it in your
browser on this machine; the agent gets no address.

## Talking to a manifold

A person can talk to any manifold from the canvas and have the voice work it. Voice is on by default for every
manifold on the machine: press **Talk**. The voice is the manifold's host: it says what is here, asks what you are
trying to do, and builds toward it in small steps — sections, the first cards, the purpose — one question at a time. It
can act, place and arrange, nothing more; Codex answers when it is on the machine (no key to add), else xAI with a key. Three voices answer: xAI's or OpenAI's realtime model with a key, or Codex on its
own sign-in. Change the default once, or one manifold's own word:

```bash
manifold key add XAI_API_KEY
manifold -m desk voice default on can=act,place,arrange,agents provider=openai   # every manifold here, unless it says otherwise
manifold -m desk voice on provider=codex can=act,place                    # this manifold's own word (voice off: off here)
manifold -m desk voice default                                            # what holds
```

Press **Talk** on the canvas. The voice is an agent like any other: a run with the grant you gave, every command in
the feed, the one `manifold` tool, and `agent` to start Claude or Codex on a longer task when `agents` is in the grant.
Approving, keys and members stay yours: the voice asks, you press. The browser does the microphone and speaker; the
key never leaves the core.

With `provider=codex` the core starts a `codex app-server` on this machine for the conversation. Codex negotiates the
call on your Codex sign-in and is the voice's hands: a thread with no shell and one tool, `manifold`, on the voice run's
socket, so it does exactly what the grant allows and every command is in the feed. The audio goes between your browser
and the model directly (WebRTC); the core passes the handshake, the transcripts and the tool calls. Codex runs here, so
this voice reaches only this machine's manifolds. Voices: juniper, maple, spruce, ember, vale, breeze, arbor, sol, cove.

## Hybrid minds

```bash
manifold mind new "SPX mind" --goal "find SPX contracts worth trading when the index moves" --router gemma4:e4b --specialists sonnet,opus --watch "option_chain.spot > 7800"
```

A mind is a manifold where several models share one Memory, one Questions and Findings and one Brief, each sized to what
it costs: gates watch for free, a router on a local model is woken with what changed and decides — a small thing itself,
or `ask sonnet "…"` with a task it writes — frontier specialists do the work and leave it on the nodes, and the Judge is
System One for a probability. Nothing runs on a timer.

## Finding things

Agents search, never browse. `find <words>` answers in one short ranked list across a manifold's cards, its types, its
docs, the node library and the machine's tools, each line with the command that uses it. `library` alone is a map of the
domains that fit the manifold's purpose (System One judges that once, when a key is held); `library <words>` and
`tools <words>` search; `tools <name>` shows one tool. Measured on 27 plain asks: the right type lands in the top five
96% of the time, in about 400 tokens, where a listing cost up to 39,000.

## Reading the web

Agents have no browser and no network of their own: a link in a card is readable through a **Reader** card. An agent
(or you) places one — `place web/reader <section> url=https://…` — you approve the type once (it reaches the web), and
`cat` gives the page as plain markdown: title, text, links. `do <node> fetch url=…` reads another page into the same
card. The `web` tool behind it reads public pages only, never anything on your machine or network, and every page read
is in the feed. `library <words>` lets a run find a type in the node library instead of guessing its name.

## Other machines

A manifold lives on one machine. Any other machine opens it by invitation, one manifold at a time, at a **level**:

| level | who | may |
|---|---|---|
| 0 · Owner | your other machine | everything, as you: private sections, every command, approving |
| 1 · Builder | a person | read, press actions, place and arrange cards in the shared sections |
| 2 · Operator | a person | read, and press actions on cards in the shared sections |
| 3 · Viewer | a person | read what is in the shared sections |

On the canvas: Activity → Share, press a level, Copy; the Join card on the other machine's home page takes the code. A
level-0 code works once and for ten minutes; a person's once and for 24 hours. The same from a terminal:

```bash
manifold -m desk share --level 0        # your other machine; there: manifold join <code>
manifold -m desk share --level 2        # a friend as Operator (0 Owner · 1 Builder · 2 Operator · 3 Viewer), within --hours, for --people
manifold join <code>                    # on the other machine; then manifold -m desk ls, or pick it on the canvas
manifold -m desk members                # who is in, at which level; members rm <name> ends one; members allow <name> <section> opens a private section
```

A machine of yours works in that manifold as you do, private sections and every command, and sees nothing else of the
machine it lives on; both machines run their own Manifold. A friend never sees a private section until you allow it by
name, never your keys, and never another manifold. Your agents and your voice run on the machine you are at and reach the
manifold over its link. `private` is granted to a session bound to one manifold, never to one that reaches several.

A canvas on any machine shows what that machine's agents read: the docs, the cards, the library and who is here all
come from the machine the manifold lives on, computed once, the way an agent's commands are answered there. You write a
manifold's docs from any machine of yours; a friend reads them.

## Where things are

| | |
|---|---|
| your manifolds, keys' names, feeds | `~/.manifold` (or `MANIFOLD_HOME`) |
| a manifold | a folder: `layout.json`, `nodes/<type>/` (`node.json`, `node.py`, `view.html`), `docs/` |
| the node library | shipped in the package; `MANIFOLD_LIBRARY` points elsewhere |
| the door | the process that carries connections between machines (Rust; `door/` in the source) |
| the canvas | `http://127.0.0.1:8730` |

The package contains code, the node library with synthetic sample data, and the door binary; nothing from the
machine it was built on. Everything you make lives in your home folder. A key goes to the macOS keychain, never to
a file. Nothing leaves your machine except what you grant to a machine you invited, through the door.

## Adding a library or a service

A tool is how cards reach a library or a service. An agent drafts one — `write tool/<name>/tool.json`, `tool.py`, a doc —
`check tool/<name>` reads it over, and you accept it on the canvas (Nodes → drafts) or with `accept tool/<name>`: that
installs its packages in an environment of its own and makes it a tool of the machine. Then cards use it. The first one
shipped this way is Manim: `manifold tool add library/tools/manim`, then place `math_visual/manim_scene`. A card that needs
an API key says so and shows a field with the key's name: paste the value, save, it gathers.

## Building a node

A node is three files. `node.json` says what it answers, its settings and the shape of its value. `node.py` has
`gather(m, s)`, which returns the value, and `act_<name>(m, s, …)` for each action. `view.html` draws the card.
`manifold bench <folder> --save --shot` runs one without a core. `library/GUIDE.md` is how library nodes are built.

## Development

```bash
git clone … && cd manifold && uv venv --python 3.13 && uv pip install -e ".[dev]"
(cd door && cargo build --release)          # the door; without it the Python door runs
.venv/bin/python -m pytest -q
```

`DECISIONS.md` holds every design decision with its reason and what would prove it wrong. `AUDIT.md` records what a
hostile machine was tried against and what remains unproven. Apache-2.0.
