Agent Optimizer

Agent Optimizer turns open-ended agent instructions into a decomposable, observable, recoverable execution plan. The current implementation provides a Python runtime skeleton, a logical optimizer that compiles requests into SPEC DAGs, and file-backed runtime artifacts for simulated execution.

Repository Layout

• src/agent_optimizer/ contains the importable Python package and CLI entrypoint.
• tests/ contains unit, smoke, and optional integration tests.
• docs/ contains the design notes for the control plane, data plane, feedback plane, and optimizer behavior.
• docs/assets/PDDL_NL.pdf contains the NL-PDDL reference material used by the benchmark-oriented tests and design work.

Quick Start

python -m pip install -e ".[dev]"
python -m pytest -q
agent-optimizer plan --instruction "Build a runnable simulated plan."

Start the local web UI to submit a natural-language task and inspect the logical DAG, physical plan, and execution timeline:

agent-optimizer ui --host 127.0.0.1 --port 8765 --open

For source-tree execution without installing first, set PYTHONPATH to src:

$env:PYTHONPATH = "src"
python -m agent_optimizer --help

Public API

from agent_optimizer import build_runtime, plan_instruction, run_instruction

runtime = build_runtime(".agent_optimizer_runtime")
report = plan_instruction("Compile the request into a SPEC DAG.", runtime=runtime)
print(report.to_dict())

Planning engine helpers are available from agent_optimizer.control_plane.planning_engine, including build_schema_pool, compile_spec_dag, and the DeepSeek entailment judge.

DeepSeek Integration

Live semantic entailment uses DeepSeek's OpenAI-compatible chat completions API. Configure it with environment variables when running integration paths:

• DEEPSEEK_API_KEY
• DEEPSEEK_BASE_URL (optional, defaults to https://api.deepseek.com)
• DEEPSEEK_MODEL (optional, defaults to deepseek-chat for the runtime LLM client; the NL-PDDL entailment helper defaults to deepseek-v4-flash when used directly)

Tests marked integration are skipped unless DEEPSEEK_API_KEY is present.

Development

Runtime outputs, test artifacts, caches, local memory files, and virtual environments are intentionally ignored by Git. Keep generated artifacts out of commits and validate changes with python -m pytest -q before staging.

License

MIT. See LICENSE.