Metadata-Version: 2.4
Name: naoru
Version: 0.1.3
Summary: Naoru — generic autonomous code-repair engine (drive → judge → fix → red-first oracle gate).
Author: Unpossible Creations, Inc.
License-Expression: LicenseRef-Naoru-Research-Preview
Project-URL: Homepage, https://naoru.dev
Project-URL: Company, https://unpossiblecreations.ai
Project-URL: License, https://naoru.dev/license/
Project-URL: Terms, https://naoru.dev/terms/
Project-URL: Privacy, https://naoru.dev/privacy/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: obra-host
Requires-Dist: obra; extra == "obra-host"
Dynamic: license-file

# Naoru

**Naoru** (Japanese 治る/直る, "to be healed / to be fixed") is a generic, host-agnostic
**autonomous code-repair engine**: it drives a system-under-test, judges the result, has an
LLM worker propose a fix in an isolated worktree, and gates any autonomous commit behind a
deterministic **red-first oracle** (RED→GREEN, N-of-M, fixer-blind).

The import package is `fix_engine`, the distribution is `naoru`. **Research preview** —
free for personal, non-commercial U.S. technical evaluation only, provided AS IS with no
warranty, not for redistribution, business use, or commercial use.
© Unpossible Creations, Inc. (see https://naoru.dev/license/ — Naoru Research Preview
License, and https://naoru.dev/privacy/).

Naoru can execute commands, call third-party LLM providers, write code, alter Git state, leak
secrets, incur provider charges, and commit autonomously. Use it only on version-controlled
personal test code you can revert. First functional use requires exact acceptance:

```sh
naoru config --accept-license "I ACCEPT"
```

Naoru stores a local acceptance receipt on your machine and does not send that receipt to
Unpossible Creations.

## The three seams

The engine core imports **zero** host code. A host binds it to an environment via
`fix_engine.host.configure_host(...)`:

- **Executor** (`fix_engine.executor`) — launch the system-under-test, stream, detect
  terminal. Ships with a generic `adapters.command_executor` (run any build/test command).
- **OutcomePlugin** (`fix_engine.outcome`) — judge a run RED/GREEN via machine-checkable
  predicates (exit code, traceback signature, contract violation, output substring, non-crash).
- **HostServices** (`fix_engine.host`) — LLM dispatch, runtime paths, tooling discovery,
  provider classification, and config UI, supplied by the host.

Plus `fix_engine.oracle` (the mandatory commit gate), `fix_engine.safety` (sandboxed-by-default
profile), `fix_engine.worker` (the bounded fix worker), `fix_engine.gates` (public validation
outcome contract), and `fix_engine.worktree`.

## What's new — the autonomous test-and-improve product

Beyond the engine primitives, naoru now ships a runnable local surface so an eligible individual
can install it, declare checks, and run autonomous missions against personal test software:

- **Declarative leaves** (`fix_engine.leaves`) — author checks in `.toml`/`.json` (a command + a
  pass-predicate); `naoru leaves generate` proposes a starter set from your personal test repo's
  tooling.
- **Leaf authoring guidance** — `naoru help leaf-authoring` and the leaf authoring guide explain
  how to turn repo-local checks into high-signal autonomous repair leaves.
- **Starter leaf rendering** preserves invocation metadata such as working directory, timeout,
  tags, enabled state, and per-leaf fix-loop caps when writing TOML.
- **Mission-driven loop** — `naoru run --mission <…>`: `test-and-fix-bugs` (red-first oracle,
  auto-commit), `improve-performance` (metric gate, auto-commit), `improve-ux` /
  `general-improvement` (propose-a-patch for review, never auto-commit). The LLM is **inherited
  from Naoru role policy plus your host config** (no provider hardcoded); flags override subject
  to the configured reasoning floor.
- **`naoru config`** — open the host's provider/model picker. **Conservative defaults** (sandboxed,
  gate-required commits); `--show-resolved` prints the effective Naoru role policy as JSON;
  `--unsafe` is explicit opt-in. Use `naoru --help` and subcommand `--help` for flag reference.

Start at **https://naoru.dev/docs/onboarding/**; architecture at
**https://naoru.dev/docs/architecture/harness/**; leaf authoring at
**https://naoru.dev/docs/guides/leaf-authoring/**; a runnable demo is at
**https://naoru.dev/examples/**. For turnkey local use, install `naoru[obra-host]`.

## Standalone invariant

`fix_engine` must never import a host product directly. Enforced by
`tests/test_fix_engine_boundary.py`; a fresh interpreter importing the full core pulls zero host
modules (`tests/test_fix_engine_portability.py`).

## Develop

```bash
uv venv && uv pip install -e . && python -m pytest tests/ -q
```

## Releasing

**Wheel-only** (never an sdist) — the public artifact is the wheel, and the license does not grant
redistribution or modification rights. Internal maintainers use the guarded release pipeline, which
builds the wheel and runs the hard verifier before any publish step. The verifier alone is
`python scripts/verify_wheel.py [wheel]`.
