Metadata-Version: 2.4
Name: gnos
Version: 0.0.1
Summary: Local-first verifier for content-addressed documents
Author: Jan T. Müller
License: MIT License
        
        Copyright (c) 2026 Jan T. Müller
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# gnos

gnos is a local-first tool for managing document chunks as manifests. Add files, attest reproducibility, and materialize documents back to disk.

## Quick start

```bash
gnos init

gnos add README.md

gnos materialize doc <doc_id> --output README.out.md
```

## What you can do

- Add files and store their chunks locally.
- Generate doc-manifests that describe how to reconstruct the original bytes.
- Attest that a manifest can reproduce the original document.
- Materialize documents back to disk when you need them.
- Bring your own chunkers for custom strategies.

## Why use gnos?

- **Verifiable manifests.** A stable schema that actually reconstructs the original bytes.
- **Local chunk store.** Chunks are content-addressed and live on your machine.
- **Rebuild anytime.** Materialize documents back to disk from manifests + chunks.
- **Derive safely.** Create alternate chunk views without changing identity.

Compared to typical chunking tools, gnos gives you a concrete manifest format and a local store you can trust.

## Common workflows

### Add a file

```bash
gnos add notes.md
```

### Add a directory as a collection

```bash
gnos add --collection docs/
```

### Verify a manifest directly

```bash
gnos attest manifest <manifest_hash>
```

### Shallow integrity check (hash-only)

```bash
gnos attest manifest <manifest_hash> --shallow
```

### Derive a non-identity manifest

```bash
gnos derive <doc_manifest_hash> --chunking <method>
```

### Materialize a collection

```bash
gnos materialize collection <collection_id> --dir ./out
```

## Commands (v1)

- `gnos init`
- `gnos add <path>`
- `gnos add --collection <path>`
- `gnos attest manifest <manifest_hash> [--doc-id H] [--shallow]`
- `gnos attest file <path> --doc-id H`
- `gnos attest doc <doc_id>`
- `gnos derive <manifest_hash> --chunking <method>`
- `gnos materialize doc <doc_id> --output <path>`
- `gnos materialize collection <collection_id> --dir <path>`
- `gnos status [--doc <doc_id>]`
- `gnos chunker list [--verbose]`
- `gnos inspect <hash>`
- `gnos list --objects|--documents|--document-manifests|--collection-manifests|--derived-manifests`
- `gnos --version`

## How it works (short)

- Documents are raw bytes. The document hash is the identity.
- Chunks are stored by hash. Manifests describe how to reconstruct bytes.
- Attestation verifies integrity and, when applicable, reconstruction.

## Learn more

- `docs/index.md` (overview of all docs)
- `docs/spec.md` (v1 spec)
- `docs/cli.md` (CLI behavior)
- `docs/manifest.md` (manifest schemas)
- `docs/chunking.md` (chunker rules)
- `docs/plugins.md` (custom chunkers)
