Metadata-Version: 2.4
Name: quinesmith
Version: 0.1.1
Summary: Safe primitives and protocol for AI-assisted editing of templated code-generation in quine/capsule systems.
Project-URL: Homepage, https://github.com/Yufok1/Quine-Forge
Project-URL: Repository, https://github.com/Yufok1/Quine-Forge
Project-URL: Issues, https://github.com/Yufok1/Quine-Forge/issues
Project-URL: Changelog, https://github.com/Yufok1/Quine-Forge/blob/main/CHANGELOG.md
Project-URL: Protocol, https://github.com/Yufok1/Quine-Forge/blob/main/docs/protocol.md
Project-URL: Threat Model, https://github.com/Yufok1/Quine-Forge/blob/main/SECURITY.md
Author: Yufok1
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-tooling,brotology,capsule,code-generation,metaprogramming,ouroboros,provenance,quine,supply-chain,template
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: provenance
Requires-Dist: cascade-lattice>=0.8.2; extra == 'provenance'
Description-Content-Type: text/markdown

# quinesmith

> Safe primitives and protocol for AI-assisted editing of templated
> code-generation in quine/capsule systems.

`quinesmith` codifies the **Quine Template Edit Protocol** as a constructive
suite of Python primitives for AI agents working on self-generating code.

It does not perform edits. It does not execute verification. It provides:

- **Level / brace tracking** — the doubling rule (`braces_required = 2^level`)
  as a checked, typed primitive.
- **Transformation registry** — the nine canonical Level-1 transforms.
- **Failure mode taxonomy** — every known quine-template failure class as
  an enum, classifiable from symptom.
- **Audit checklists** — the pre-edit and stop-and-audit conditions as
  callable predicates the agent must satisfy.
- **Verification preparers** — boundary-respecting functions that return
  shell-runnable command strings for the *human operator*. The agent
  prepares; the operator runs.

This package is **digital fire**. See
[SECURITY.md](https://github.com/Yufok1/Quine-Forge/blob/main/SECURITY.md)
for the threat model and the boundary statement.

Quine Forge is the project and repository. `quinesmith` is the Python package
and import name.

## What this is not

- It is not an editor. It does not modify quine source.
- It is not a runtime. It does not execute, compile, or regenerate.
- It is not a doctrine. The operator contract that governs how an agent
  *uses* this package lives in
  [`brotology-field-guide`](https://pypi.org/project/brotology-field-guide/) —
  `quinesmith` is the *operational primitives*, not the doctrinal stance.

## Install

```bash
pip install quinesmith
```

With provenance / cascade-lattice receipts:

```bash
pip install "quinesmith[provenance]"
```

## Quick example

```python
from quinesmith import Level, braces_required, FailureMode
from quinesmith import verify

# How many braces does a literal `{x}` need at template level 1?
braces_required(Level.TEMPLATE)
# -> 2

# Diagnose a symptom against the canonical taxonomy:
FailureMode.from_symptom(
    "Compiles, emission produces {x} literal where a value was wanted"
)
# -> FailureMode.OVER_DOUBLED_BRACES

# Prepare verification commands. The OPERATOR runs these:
print(verify.prepare_commands("my_quine.py"))
# python -m py_compile my_quine.py
# python my_quine.py --verify-quine
# python my_quine.py --emit > regen.py
# python -m py_compile regen.py
# diff my_quine.py regen.py
```

## Boundary

The agent prepares; the operator runs. There is no `verify.run(...)`. There
will not be one. The protocol's safety boundary (§7.7, §8) is enforced at
the API level. See
[SECURITY.md](https://github.com/Yufok1/Quine-Forge/blob/main/SECURITY.md#boundary-statement).

## Protocol reference

The full Quine Template Edit Protocol is published at
[`docs/protocol.md`](https://github.com/Yufok1/Quine-Forge/blob/main/docs/protocol.md)
and bundled in the source distribution under `docs/protocol.md`.

## Provenance

Every release ships:

- Apache-2.0 licensing
- GitHub release workflow for PyPI Trusted Publishing
- a no-execution verification boundary for AI-assisted quine work
- optional `cascade-lattice` integration for downstream provenance receipts

Verify a release per
[SECURITY.md](https://github.com/Yufok1/Quine-Forge/blob/main/SECURITY.md#provenance-verification).

## License

Apache License 2.0. See
[LICENSE](https://github.com/Yufok1/Quine-Forge/blob/main/LICENSE).

## Lineage

This package is part of the Ouroboros ecosystem. Companion packages:

- [`cascade-lattice`](https://pypi.org/project/cascade-lattice/) —
  composable provenance / audit primitives.
- [`brotology-field-guide`](https://pypi.org/project/brotology-field-guide/) —
  the operator contract that governs how AI agents collaborate on
  living systems.
- `quinesmith` (this package) — operational primitives for safe quine
  template editing.

## Contributing

This is a small, security-focused package. Contributions follow the
brotology operator contract: evidence-first, audit-before-implement, smallest
honest slice. See
[SECURITY.md](https://github.com/Yufok1/Quine-Forge/blob/main/SECURITY.md)
for boundary requirements that must not be relaxed.
