Fully Recursive

This repository contains a bounded recursive self-improvement sandbox. It is not an AGI or ASI system. It is a practical research scaffold for studying one narrow loop:

1. Start from a constrained policy specification.
2. Generate candidate policy mutations from a fixed registry.
3. Evaluate candidates against a benchmark suite.
4. Promote a candidate only if it improves fitness and passes safety gates.
5. Repeat with the promoted policy as the next parent.

The point is to make the recursive improvement loop inspectable and testable without giving the system open-ended access to rewrite code, run generated programs, access the network, or modify its own operating constraints.

Quick Start

Run the demo loop:

PYTHONPATH=src python -m fullyrecursive.cli run --iterations 8 --out runs/demo

Evaluate the built-in seed policy:

PYTHONPATH=src python -m fullyrecursive.cli evaluate

Write the seed policy to disk:

PYTHONPATH=src python -m fullyrecursive.cli init-policy --out examples/seed_policy.json

Run tests:

PYTHONPATH=src python -m pytest

After installing the project, the shorter command also works:

fullyrecursive run --iterations 8 --out runs/demo

Architecture

The project is intentionally small:

• PolicySpec is the thing being improved. It maps benchmark domains to named solvers from a fixed registry.
• SolverRegistry contains the only executable strategies candidates may use.
• BenchmarkSuite measures policy behavior on deterministic tasks.
• NeighborMutator creates candidate policies by changing one solver at a time.
• SafetyGate validates candidate structure and rejects non-improving policies.
• RecursiveImprover coordinates evaluation, selection, promotion, and lineage logging.

This is useful for testing research questions around recursive optimization, promotion criteria, benchmark overfitting, and lineage auditing. It deliberately does not implement autonomous source-code modification or unbounded goal pursuit.

Safety Boundaries

The default loop has these hard boundaries:

• no network access;
• no generated-code execution;
• no shell access from the improver;
• no arbitrary filesystem writes outside the configured run directory;
• no candidate strategies outside the local solver registry;
• no promotion without benchmark evidence and gate approval.

Those restrictions are not incidental. They are part of the design.

Example Output

A run writes JSON artifacts under the chosen output directory:

• lineage.jsonl records each accepted promotion or stop decision.
• best_policy.json stores the final promoted policy.
• best_score.json stores the final score.

The CLI also prints a concise summary for each generation.