autoresearch_anything

autoresearch_anything is a framework for running autonomous LLM-driven research loops over any verifiable problem. You define what to propose, how to evaluate, and whether to keep results — the framework runs the loop across local or remote workers.

If you're missing anything, let me know on Discord or Twitter.

Install

pip install autoresearch_anything

Concepts

The framework has two kinds of workers:

• Impl workers — run an LLM that reads your editable files and modifies them to implement a proposed direction.
• Eval workers — run your evaluation command and return stdout.

You subclass Autoresearch to wire these together:

from autoresearch_anything import Autoresearch, Journal, EvalWorker, ImplWorker, Models, ModelConfig

class MyResearch(Autoresearch):
    journal      = MyJournal
    eval_workers = [EvalWorker(host=None, remote_dir="/path/to/project")]
    impl_workers = [ImplWorker(host=None)]
    models       = Models(
        propose   = ModelConfig(model="claude-opus-4-5", provider="anthropic"),
        commit    = ModelConfig(model="claude-opus-4-5", provider="anthropic"),
        implement = ModelConfig(model="claude-cli",      provider="claude-cli"),
        diagnose  = ModelConfig(model="claude-cli",      provider="claude-cli"),
    )
    eval_command = "python evaluate.py"
    editable     = ["model.py"]

    def propose(self, state, history):
        # Return a natural-language direction string
        ...

    def parse_result(self, stdout):
        # Parse eval stdout into a result dict
        ...

    def keep(self, result, history):
        # Return True to accept, False to discard
        return history.best is None or result["score"] > history.best["score"]

autoresearch = MyResearch()

Journal

Subclass Journal to implement state and history management:

from autoresearch_anything import Journal

class MyJournal(Journal):
    def get_state(self):
        # Return {relative_path: content} of current editable files
        ...

    def get_history(self):
        # Return history as a string for the propose prompt
        ...

    def record(self, result):
        # Persist a result
        ...

    def apply(self):
        # Accept the current impl (e.g. copy files into place)
        ...

    def revert(self):
        # Discard the current impl
        ...

Run

Point autoresearch_run at a package that exports an autoresearch instance:

autoresearch_run my_autoresearch_package

The impl worker entry point (autoresearch_impl_runner) is launched automatically on impl workers — you don't need to call it directly.

Programmatic API

You can also launch from Python directly:

from autoresearch_anything import run_from_instance

run_from_instance(autoresearch)

Troubleshooting

If something's broken or confusing, hit me up on Discord or Twitter.