Metadata-Version: 2.4
Name: afo
Version: 0.1.3
Summary: Agent Focused Optimization framework for bounded agent optimization loops
Project-URL: Homepage, https://pypi.org/project/afo/
Author: Triet
License-Expression: GPL-3.0-only
License-File: LICENSE
Keywords: agents,optimization,sysml,systems-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Provides-Extra: http
Provides-Extra: ollama
Provides-Extra: openai
Requires-Dist: openai>=1; extra == 'openai'
Description-Content-Type: text/markdown

# AFO

Agent Focused Optimization (AFO) is a small Python framework for bounded
agent optimization loops.

AFO separates the agent that chooses actions from the world model that verifies,
evaluates, records, and checks convergence. The package is intentionally generic:
users provide their own design space, evaluation model, tools, and convergence
criteria.

## Installation

```bash
python -m pip install afo
```

For local development from this repository:

```bash
python -m pip install -e .
```

## Quick Start

Run the local LLM quadratic example with Ollama:

```bash
python examples/quadratic/run_quadratic.py
```

AFO saves inspectable run artifacts by default under `outputs/runs/<run-id>/`,
including `events.jsonl`, `run_log.txt`, observations, and a manifest.

## Core Concepts

- `Agent`: selects the next bounded tool call.
- `ActionSpace`: declares the tools the agent may use.
- `DesignSpace`: verifies proposed design variables.
- `EvaluationModel`: evaluates verified design variables.
- `WorldModel`: verifies, evaluates, records, and checks convergence.
- `RunLoop`: executes the default AFO loop.
- `RunRecorder`: saves a local run directory for later inspection.

## Minimal Example

```python
from afo.logical.world_model.evaluation_model import EvaluationModel
from afo.logical.world_model.evaluation_result import EvaluationResult


class MyEvaluationModel(EvaluationModel):
    def evaluate(self, design_variable, evaluation_inputs=None):
        return EvaluationResult(value=design_variable["x"] ** 2)
```

See `examples/quadratic/` for a complete local LLM example.

## Documentation

- `docs/getting-started.md`: install AFO and run the quadratic example.
- `docs/concepts.md`: understand the AFO loop and core contracts.

## Examples

- `examples/quadratic/`: local LLM example with one design variable.
- `examples/sellar/`: local LLM example with coupled disciplines and constraints.

## SysML

The repository includes `model/AFO.sysml`, the SysML source describing the
framework requirements, functional actions, logical contracts, and physical flow.

## License

AFO is distributed under the GNU General Public License v3.0 only.
