Metadata-Version: 2.4
Name: my-arch
Version: 2.1.0
Summary: An architectonic framework for building cognitive software.
Author: Robb Doering
Author-email: Robb Doering <robb@doering.ai>
License-Expression: MPL-2.0
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: asyncpg>=0.30.0
Requires-Dist: coverage>=7.10.5
Requires-Dist: gitpython>=3.1.45
Requires-Dist: greenlet>=3.2.4
Requires-Dist: jinja2>=3.1.6
Requires-Dist: logfire>=4.0.0
Requires-Dist: more-itertools>=10.7.0
Requires-Dist: my-basis>=1.0.0
Requires-Dist: pandas>=2.3.1
Requires-Dist: mypy>=1.17.1
Requires-Dist: pydantic>=2.11.7
Requires-Dist: regex>=2025.7.34
Requires-Dist: sqlmodel>=0.0.39
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: yapf>=0.43.0
Requires-Dist: dspy>=2.6.10 ; extra == 'assay'
Requires-Dist: pyratatui>=0.2.9 ; extra == 'terminal'
Requires-Python: >=3.14
Project-URL: Documentation, https://arch.docs.doering.ai/
Provides-Extra: assay
Provides-Extra: terminal
Description-Content-Type: text/markdown

<!-- readme-header:begin -->

<div align="center">

<img src="assets/logo_512.png" alt="myArch logo" width="180">

# myArch: _A Systematic Development Framework_

<p align="center">
  <a href="https://gitlab.com/doering-ai/libs/arch/-/pipelines"><img src="https://img.shields.io/gitlab/pipeline-status/doering-ai%2Flibs/arch" alt="pipeline status"></a> <img src="https://img.shields.io/badge/version-2.1.0-blue" alt="version">
</p>

<p align="center">
  <img src="https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=precommit" alt="pre-commit"> <a href="https://github.com/facebook/pyrefly"><img src="https://img.shields.io/endpoint?url=https://pyrefly.org/badge.json" alt="pyrefly"></a> <a href="https://github.com/astral-sh/ruff"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json" alt="ruff"></a>
</p>

</div>

<!-- readme-header:end -->

> Left-rule blocks mark artificial prose; quotations retain their own attribution.

<blockquote class="artificial-prose">

**myArch** gives structure an address: indexed headings for documents, and a separate four-level cell model for architectonic Python code.
You can inspect a document's numbering, preview a repair, and apply it without making every heading look alike.

</blockquote>

**Documentation:** [arch.docs.doering.ai](https://arch.docs.doering.ai/)

## Installation

<blockquote class="artificial-prose">

Use Python 3.14+.
These examples follow the 2.1 source tree; the published 1.0 package uses an older configuration schema.
Install from Git for the behavior described here ([release notes](RELEASE.md)):

</blockquote>

```console
uv tool install 'git+https://gitlab.com/doering-ai/libs/arch.git'
# Or, in an activated Python 3.14+ virtual environment:
python -m pip install 'git+https://gitlab.com/doering-ai/libs/arch.git'
```

## Try an address

```console
$ arch --json idx parse '1.2'
{"version": 1, "rendered": "1.2", "ordinals": [0, 1], "depth": 2, "styles": ["number", "number"]}
```

<blockquote class="artificial-prose">

The visible address is one-based; its internal ordinals are zero-based.
Document indexes can be numeric, alphabetic, Roman, or symbolic, with dotted or compact rendering and optional markers and wrappers.
Their depth is arbitrary: changing the presentation doesn't change the place.

</blockquote>

## Inspect, then apply

<blockquote class="artificial-prose">

From this repository's checkout, these commands inspect one configured document:

</blockquote>

```console
arch check docs/idx.md
arch --json plan docs/idx.md
arch format --check docs/idx.md
arch format --diff docs/idx.md
```

<blockquote class="artificial-prose">

`check` reports index diagnostics; `plan` exposes the proposed edits.
The two `format` commands check header presentation or print a patch without writing it.
When you're ready, `apply` writes the index plan, while bare `format` writes the header-format plan:

</blockquote>

```console
arch apply docs/idx.md
arch format docs/idx.md
```

<blockquote class="artificial-prose">

Each file is planned, checked against its source digest, and atomically replaced.
Its newline convention and final-newline state survive the edit.
This is a per-file write boundary.

</blockquote>

## Choose what participates

<blockquote class="artificial-prose">

Seeing an index doesn't enroll a file.
Index planning needs an `indexing.paths` rule or an explicit `--spec` override.
Within an enrolled file, `observed` inserts only at hierarchy depths already represented there; `all` is allowed only on an explicit path rule.

Configuration precedence is command flags, an explicit `--config`, the nearest `.arch.yaml`, `~/.config/my/arch.yaml`, then built-ins.
Index enrollment and header formatting have independent selectors, with higher-precedence rules tried first.
For example:

</blockquote>

```yaml
specs:
    formal-markdown:
        styles: [number]
        separator: '.'
        wrapper: '`'

indexing:
    default: off
    insertion: observed
    paths:
        - glob: 'policies/**'
          spec: formal-markdown
          insertion: all

header_mode: flex

header_defaults:
    markdown: markdown
    source: source
    typst: off
    rst: off
    unknown: off

header_paths:
    - path: 'README.md'
      profile: off

ignore:
    - 'vendor/**'
```

<blockquote class="artificial-prose">

Header formatting defaults to `flex`: existing indexed shapes establish file-local level precedents, preserving authored presentation.
Use `header_mode: strict` or `arch format --mode strict` when the configured profile should set case and geometry.
The built-in Markdown profile keeps title case, leaves H1 unindexed, and renders recognized H2+ indexes as dotted backtick tags such as `` `1.2` ``.
Typst, reStructuredText, and unknown suffixes remain off until they have structural adapters.

Use `arch config show --path FILE` to inspect the selected family, enrollment, spec/profile sources, insertion policy, and matching ignore rule.

</blockquote>

## Tag a multi-file work

<blockquote class="artificial-prose">

An edition split into chapter files, with an `index.md` whose `toctree` lists them, is tagged as one outline by `arch book`.
Every heading but a part heading gets a backtick tag such as `` `3.2.` ``, front matter takes `` `0.` ``, and titles are never edited.
A part heading, the `# [Commentary, part 2]` that opens each later file of a section cut in parts, continues the H1 before it and takes no tag.
A work is touched only when `--spec` names a backtick spec (the built-in `lit` is one) or an `indexing.paths` rule enrolls its `index.md`:

</blockquote>

```console
arch book check --spec lit works/demo
arch book plan --spec lit works/demo
arch book apply --spec lit works/demo
arch book outline --spec lit works/demo
```

<blockquote class="artificial-prose">

`plan` and `apply` print the old-to-new renumber map for tags that shift when a heading is inserted or removed.
`arch.idx.read_outline()` gives other tools each heading's idx, file, line, level, and title straight from the tags, with no sidecar file.

</blockquote>

## Two index domains

<blockquote class="artificial-prose">

`arch.idx.Idx` is the non-empty, arbitrary-depth document address used above.
`arch.Quad` is the original fixed, four-place architectonic address; `arch.Idx` remains its compatibility name.
A Quad admits the empty root and abstract `a` / `b` halves, with a special four-branch ancestry.
These domains are separate, not subtypes of one another.

The Python library adds `Lang` and `Cell`, the `Architectonic` registry and default `ARCH` instance, and source-code models including `Module`, `File`, and `Element`.
The `thesis`, `antithesis`, and `synthesis` decorators alias an element's three moments onto its class.
The [package guide](arch/README.md) points to these entry points.

</blockquote>

## Terminal workspace

<blockquote class="artificial-prose">

With the optional `terminal` extra installed, bare `arch` opens the PyRatatui browser when stdin and stdout are terminals.
For captured output or scripts, use a subcommand.
`arch spec --input headers.yaml --output headers.yaml` opens the profile editor for an existing specification and can save changes to that file.
See the [header formatting guide](https://arch.docs.doering.ai/headers.html) for the editor and `HeaderSpec`.

</blockquote>

## Further reading

- [Document index guide](https://arch.docs.doering.ai/idx.html)
- [Tagging a work across chapter files](https://arch.docs.doering.ai/book.html)
- [Index design](https://arch.docs.doering.ai/idx-design.html)
- [Document index API](https://arch.docs.doering.ai/idx-api.html)
- [Header formatting](https://arch.docs.doering.ai/headers.html)
