# Hyperiad and Arity Science: a guide for AI agents

You are reading the entry point for agents working with the Arity Science research programme and its
computational framework, Hyperiad (version 0.1.0, build d5c1a26). Read this guide, then the knowledge
base, then the notebooks.

## What this is

Hyperiad is the computational framework built to conduct the research of the Arity Science project. Compute and visualize hypermatrices, hypergraphs and rewrite rules with their causal structure. Our findings are published as Hyperiad notebooks, so every figure can be recomputed, changed and downloaded.

Arity Science studies the compositional structure of higher-order systems: n-ary algebras, hypergraphs,
hypermatrices and higher-arity categories. Site: https://arity.science

## Where things stand

- Knowledge base (settled definitions, claims with their status and evidence): https://arity.science/hyperiad/agents/knowledge.md
- The same as JSON: https://arity.science/hyperiad/agents/catalog.json
- Published findings, each a Hyperiad notebook:
  - None yet. Findings are listed at https://arity.science/#findings once published.
- Papers and talks of the team: listed in https://arity.science/llms.txt

Hyperiad is in early development. Definitions marked stable and claims marked proved or formalized are the
firmest ground; `supported` means computational evidence, not proof. Treat anything else as open.

## Running Hyperiad

- In a browser: https://arity.science/hyperiad/notebook/ runs Python (Pyodide) in the page; nothing to install.
- Example notebooks:
  - Hyperiad: arrays and hypergraphs: https://arity.science/hyperiad/examples/hypermatrix-basics/ (source: https://arity.science/hyperiad/examples/hypermatrix-basics/notebook.json)
  - Hypergraph rewriting: diagrams and composition: https://arity.science/hyperiad/examples/hypergraph-rewriting/ (source: https://arity.science/hyperiad/examples/hypergraph-rewriting/notebook.json)
  - Input–output edges: a first look: https://arity.science/hyperiad/examples/input-output-edges/ (source: https://arity.science/hyperiad/examples/input-output-edges/notebook.json)
  - Infrageometry foundations: https://arity.science/hyperiad/examples/infrageometry-foundations/ (source: https://arity.science/hyperiad/examples/infrageometry-foundations/notebook.json)
- Builtins: https://arity.science/hyperiad/agents/reference.md
- Over HTTP, for computations too large for the browser:
  - `GET https://arity.science/api/hyperiad/info` returns the server's limits.
  - `POST https://arity.science/api/hyperiad/run` with JSON `{"code": "...", "replay": ["earlier cell", ...]}` runs `code`
    after replaying the earlier cells, and returns `{"status", "outputs"}`. Outputs are text, LaTeX, SVG
    drawings or errors.
  - Limits: estimated cost up to 2e9 operations, 60 s and 1024 MB per job; 4 jobs a minute and 30 an hour per visitor; 30 a minute overall. It is a shared public service for small jobs: do not loop over it.
- Source code: https://github.com/Zaphyz/hyperiad. The browser kernel's Python is also at
  https://arity.science/hyperiad/pysrc.json (`{"files": {path: source}}`).

### The language (provisional)

| written | meaning |
|---|---|
| `f(x, y, k = v)` | call, with a keyword option |
| `[a, b]`, `{k: v}` | list, association |
| `a[i, j]`, `a["Order"]` | part (1-based, negative from the end), array property |
| `a -> b` | rule |
| `x => body`, `(x, y) => body` | function |
| `x = e`, `f(x, y) = body` | assignment, definition |
| `+ - * /`, `^` or `**` | arithmetic (exact on integers and fractions) |
| `== != < <= > >=`, `and or not` | comparison, logic |
| `true false null`, `# comment` | constants, comments |

Statements are separated by newlines or `;`. Newlines inside brackets continue the statement.
A cell shows its last value, and a trailing `;` suppresses it.

### The notebook format

A notebook is JSON: `{"title": "...", "cells": [...]}`. A cell is `{"type": "text", "source": "<Markdown,
$LaTeX$>"}` or `{"type": "code", "source": "<Hyperiad code>"}`. Optional: `"contents": true` adds a contents
sidebar from the headings. In text cells, a block quote opening with **Definition**, **Claim**, **Question**,
**Proposal** or **Example** is set as a box of that kind. Outputs are computed when the notebook runs; do not
write them.

## Contributing

The source is at https://github.com/Zaphyz/hyperiad, open to forks and pull requests. Read its AGENTS.md and CONTRIBUTING.md, fork it, work on a branch, run its checks (`uv run pytest`, `uv run ruff check .`) and open a pull request. Notebooks are contributions too (below).

A contribution is a Hyperiad notebook that states a question, computes the evidence and draws it. Keep to the
project's conventions: mark each result as observed (computed), proved or conjectured; prefer the smallest
example that shows the point; draw objects rather than printing them. Definitions are decided by the research
team: when a step needs one that is not in the knowledge base, ask rather than choose.