Metadata-Version: 2.5
Name: openmodus
Version: 0.0.1
Summary: Evidence-backed authored knowledge for coding agents.
Author: Modus contributors
License-Expression: MIT
License-File: LICENSE
Keywords: code-intelligence,coding-agents,developer-tools,knowledge-management,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development
Requires-Python: >=3.11
Requires-Dist: click<8.4,>=8.1.0
Requires-Dist: jsonschema<5.0,>=4.0
Requires-Dist: networkx<4.0,>=3.4
Requires-Dist: pyyaml<7.0,>=6.0
Requires-Dist: questionary<3.0,>=2.1
Requires-Dist: tree-sitter-c-sharp<0.25,>=0.23
Requires-Dist: tree-sitter-c<0.25,>=0.23
Requires-Dist: tree-sitter-cpp<0.25,>=0.23
Requires-Dist: tree-sitter-go<0.26,>=0.23
Requires-Dist: tree-sitter-java<0.25,>=0.23
Requires-Dist: tree-sitter-javascript<0.26,>=0.23
Requires-Dist: tree-sitter-kotlin<2.0,>=1.0
Requires-Dist: tree-sitter-php<0.25,>=0.23
Requires-Dist: tree-sitter-python<0.26,>=0.23
Requires-Dist: tree-sitter-rust<0.25,>=0.23
Requires-Dist: tree-sitter-typescript<0.25,>=0.23
Requires-Dist: tree-sitter<0.26,>=0.23.0
Requires-Dist: typer<0.26,>=0.12.0
Provides-Extra: test
Requires-Dist: coverage[toml]<8.0,>=7.0; extra == 'test'
Requires-Dist: mypy<3.0,>=1.19; extra == 'test'
Requires-Dist: pytest<10.0,>=7.0; extra == 'test'
Requires-Dist: ruff<1.0,>=0.5.0; extra == 'test'
Requires-Dist: types-jsonschema<5.0,>=4.0; extra == 'test'
Requires-Dist: types-networkx<4.0,>=3.4; extra == 'test'
Requires-Dist: types-pyyaml<7.0,>=6.0; extra == 'test'
Description-Content-Type: text/markdown

# Modus

Modus turns a repository and its business material into reviewable,
source-grounded Markdown knowledge for coding agents.

The first open-source release keeps one durable product: authored knowledge.
Source graphs are not a second database. During `/modus-init` or
`/modus-reinit`, a disposable analyzer builds an in-memory evidence graph,
projects the evidence needed for authoring, and then releases its working
state.

## Design

```text
repository bytes + build context
              │ freeze
              ▼
      CST / structural IR
              │
       project binding
              │
   compiler observations (optional)
              │
   explicit semantic reconciliation
              │
      in-memory evidence graph
              │ project
              ▼
 deterministic JSON evidence bundle
              │ current init/reinit only
              ▼
 reviewed Markdown knowledge
```

This separation is intentional:

- source bytes and build configuration answer which code was analyzed;
- CST, project binding, and compiler observations retain their own provenance;
- exact, candidate, heuristic, and unresolved relationships stay distinct;
- conflicts become diagnostics instead of being overwritten;
- a method witness points back to source rather than copying method bodies;
- business domains and modules remain an agent-and-user judgment, never a
  clustering side effect.

Ordinary knowledge use, hooks, status, and incremental updates read current
source and authored Markdown only. They cannot import or read initialization
analysis.

## Product surface

Modus installs exactly five knowledge skills:

- `using-modus` progressively adds project evidence only when the task needs it;
- `modus-init` and `modus-reinit` create or fully refresh authored knowledge;
- `modus-update-knowledge` performs an explicitly requested scoped update;
- `modus-sync-knowledge` silently revises knowledge only after a code change
  actually changes durable semantics or source anchors.

The first three authoring workflows are exposed as `/modus-init`,
`/modus-reinit`, and `/modus-update-knowledge`. `using-modus` and
`modus-sync-knowledge` are agent lifecycle helpers, not extra user workflows.
Unrelated conversations never inspect Modus state.

The project layout keeps control and data ownership visibly separate:

```text
.modus/            config, manifest, neutral skills/commands, hooks
modus/knowledge/   the only durable product data
modus/.cache/      disposable analysis and authoring state, created on demand
```

No other top-level entry belongs under `modus/`.

## Evidence bundle

Each successful build publishes one immutable bundle:

```text
modus/.cache/init-analysis/bundles/<bundleDigest>/
    ├── manifest.json
    ├── snapshot/{index.json,sources/,build-units/}
    ├── scope/{index.json,candidates/}
    ├── services/{index.json,boundaries/}
    ├── diagnostics.json
    └── evidence/{index.json,files/}
```

Each namespace is a bounded stable-key range catalog. Source files, build
units, technical candidates, service boundaries, and evidence records have
independent shards. Scope exposes explainable technical signals and navigation,
never business names or conclusions.

The bundle contract has no absolute paths, timestamps, random IDs, raw graph,
SQL database, WAL, historical generation, full-text index, or query language.
JSON is stable-sorted UTF-8 with an explicit schema version.

Publication occurs in a same-filesystem temporary directory. The manifest binds
exactly five Merkle roots; recursive validation rejects bad catalogs, records,
references, paths, digests, and orphan shards before atomic rename. Current
initialization consumes only the `BuildReceipt` returned by its own invocation.

## Commands

The supported CLI is deliberately small:

```text
modus init
modus update
modus help
modus uninstall
modus status
modus --version
```

`modus uninstall` removes managed project integration and the local CLI after
showing a preview. Authored knowledge under `modus/knowledge` is retained by
default; deleting that durable data requires the explicit
`modus uninstall --delete-knowledge` option.

Initialization Skills use one internal adapter:

```text
modus internal init-analysis build --root . --compiler auto --json
modus internal init-analysis select --root . --bundle-digest <digest> --source-snapshot-digest <digest> --view scope|services|evidence --json
```

The command is synchronous. Progress is written to stderr; JSON stdout contains
only the bundle digest, source-snapshot digest, coverage, and diagnostics
summaries. Select returns complete records under a byte/item budget and an
optional stable cursor. There is no graph update/status/query/export/doctor or
persisted progress command.

The design is informed by public ideas from CodeWiki, Aider, GitNexus,
Repomix, and OpenDeepWiki, while the implementation, contracts, tests, prompts,
and assets are independently authored for Modus. No source code from those
projects is included.

## Failure semantics

Snapshot drift, an invalid manifest, a digest mismatch, or cross-bundle mixing
fails the current analysis. A failed build does not replace the last complete
bundle, but the current init/reinit also does not consume that older bundle.
It immediately continues from current source and user material.

A local parser or compiler-provider failure lowers only the affected evidence.
It never means the repository has no business behavior. Compiler observations
cannot silently overwrite CST or project binding; reconciliation retains the
chosen result, alternatives, reason, context, and source witness.

## Workspace semantics

A workspace root never runs initialization analysis. When a user chooses to
initialize members that have no authored knowledge, each member runs as an
independent single repository. Bundle identities and evidence never cross
member roots.

## Installation

Modus is distributed on PyPI as `openmodus`, while the installed command and
Python import remain `modus`:

```bash
uv tool install openmodus
modus --version
modus init
```

Python 3.11 or newer is required.

## Development

The package supports Python 3.11–3.14.

```bash
uv sync --locked --extra test
uv run pytest
uv run ruff check .
uv run mypy
uv build
```

The architecture boundary test rejects imports of `modus.init_analysis` from
ordinary runtime packages. Distribution checks also reject legacy
`modus.graph`, SQLite stores, WAL/query code, and obsolete graph commands.

The public application boundary is intentionally narrow:

```python
from modus.init_analysis import BuildOptions, EvidenceRequest
from modus.init_analysis import build, open_bundle, select

receipt = build(".", BuildOptions(compiler_mode="auto"))
bundle = open_bundle(
    ".",
    receipt.bundle_digest,
    receipt.source_snapshot_digest,
)
scope = select(bundle, EvidenceRequest(view="scope"))
```

Everything behind these calls is implementation detail. This keeps the first
release understandable today and leaves future machine-query capabilities free
to earn their own explicit product contract later.
