Metadata-Version: 2.4
Name: autoresearch_anything
Version: 0.1.0
Summary: A framework for autonomous LLM-driven research loops over any verifiable problem
Author-email: Aaron Pazdera <aarpazdera@gmail.com>
License-Expression: Apache-2.0
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mlsweep
Dynamic: license-file

# 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](https://discord.gg/w2K2JWJGUb) or [Twitter](https://twitter.com/apaz_cli).

## Install

```sh
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:

```python
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:

```python
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:

```sh
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:

```python
from autoresearch_anything import run_from_instance

run_from_instance(autoresearch)
```

## Troubleshooting

If something's broken or confusing, hit me up on [Discord](https://discord.gg/w2K2JWJGUb) or [Twitter](https://twitter.com/apaz_cli).
