Metadata-Version: 2.4
Name: design-research-agents
Version: 0.2.0
Summary: A flexible, modular framework for researching engineering design AI agents
Author: The Design Research Collective
Maintainer-email: "Christopher C. McComb" <ccm@cmu.edu>
License-Expression: MIT
Project-URL: Homepage, https://cmudrc.github.io/design-research-agents/
Project-URL: Documentation, https://cmudrc.github.io/design-research-agents/
Project-URL: Repository, https://github.com/cmudrc/design-research-agents
Project-URL: Issues, https://github.com/cmudrc/design-research-agents/issues
Keywords: agents,llm,mcp,design,research,orchestration
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: bashkit>=0.1.4
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: openai<2,>=1.40
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pre-commit<5,>=3.7; extra == "dev"
Requires-Dist: pytest<9,>=8.2; extra == "dev"
Requires-Dist: pytest-asyncio<1,>=0.23; extra == "dev"
Requires-Dist: pytest-cov<8,>=7.0; extra == "dev"
Requires-Dist: ruff<1,>=0.6.0; extra == "dev"
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: sphinx<9,>=7.4; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid<2,>=1.0; extra == "dev"
Requires-Dist: sphinx-rtd-theme<4,>=2.0; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Provides-Extra: anthropic
Requires-Dist: anthropic<1,>=0.40; extra == "anthropic"
Provides-Extra: gemini
Requires-Dist: google-genai<2,>=1.0; extra == "gemini"
Provides-Extra: groq
Requires-Dist: groq<2,>=1.0; extra == "groq"
Provides-Extra: llama-cpp
Requires-Dist: huggingface-hub>=0.24; extra == "llama-cpp"
Requires-Dist: llama-cpp-python[server]>=0.2.90; extra == "llama-cpp"
Provides-Extra: mlx
Requires-Dist: mlx-lm>=0.14; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
Provides-Extra: transformers
Requires-Dist: huggingface-hub>=0.24; extra == "transformers"
Requires-Dist: torch<3,>=2.4; extra == "transformers"
Requires-Dist: transformers>=4.44; extra == "transformers"
Provides-Extra: vllm
Requires-Dist: vllm<1,>=0.6; (platform_system == "Linux" and python_version < "3.14") and extra == "vllm"
Provides-Extra: sglang
Requires-Dist: sglang<1,>=0.4; (platform_system == "Linux" and python_version < "3.14") and extra == "sglang"
Provides-Extra: local
Requires-Dist: huggingface-hub>=0.24; extra == "local"
Requires-Dist: llama-cpp-python[server]>=0.2.90; extra == "local"
Requires-Dist: mlx-lm>=0.14; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "local"
Requires-Dist: torch<3,>=2.4; extra == "local"
Requires-Dist: transformers>=4.44; extra == "local"
Provides-Extra: full
Requires-Dist: huggingface-hub>=0.24; extra == "full"
Requires-Dist: llama-cpp-python[server]>=0.2.90; extra == "full"
Requires-Dist: mlx-lm>=0.14; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "full"
Requires-Dist: torch<3,>=2.4; extra == "full"
Requires-Dist: transformers>=4.44; extra == "full"
Requires-Dist: vllm<1,>=0.6; (platform_system == "Linux" and python_version < "3.14") and extra == "full"
Requires-Dist: sglang<1,>=0.4; (platform_system == "Linux" and python_version < "3.14") and extra == "full"
Dynamic: license-file

# design-research-agents
[![CI](https://github.com/cmudrc/design-research-agents/actions/workflows/ci.yml/badge.svg)](https://github.com/cmudrc/design-research-agents/actions/workflows/ci.yml)
[![Coverage](https://raw.githubusercontent.com/cmudrc/design-research-agents/main/.github/badges/coverage.svg)](https://github.com/cmudrc/design-research-agents/actions/workflows/ci.yml)
[![Examples Passing](https://raw.githubusercontent.com/cmudrc/design-research-agents/main/.github/badges/examples-passing.svg)](https://github.com/cmudrc/design-research-agents/actions/workflows/ci.yml)
[![Public API In Examples](https://raw.githubusercontent.com/cmudrc/design-research-agents/main/.github/badges/examples-api-coverage.svg)](https://github.com/cmudrc/design-research-agents/actions/workflows/ci.yml)
[![Docs](https://github.com/cmudrc/design-research-agents/actions/workflows/docs-pages.yml/badge.svg)](https://github.com/cmudrc/design-research-agents/actions/workflows/docs-pages.yml)

`design-research-agents` is a modular framework for prototyping and researching engineering design AI agents.
It features shared runtime contracts, workflow orchestration, and pluggable LLM backends for quick iteration.

## Overview

This library centers on a small set of composable pieces you can run, inspect, and test:

- Two primary entry points: `DirectLLMCall` and `MultiStepAgent` (`direct`, `json`, and `code` modes)
- A tool runtime built around `Toolbox`, with callable, script, and MCP-backed tool configs
- Prebuilt orchestration patterns for plan/execute, debate, propose/critic, routing, beam search, RAG, blackboard, and conversations
- Hosted and local LLM clients, plus `ModelSelector` for backend-selection policies
- Tracing, structured `ExecutionResult` outputs, and runnable examples aimed at repeatable experiments
- A workflow runtime with explicit step primitives for model calls, tool calls, delegation, loops, and memory

## A Super Basic Agent

```python
from design_research_agents import LlamaCppServerLLMClient, MultiStepAgent

with LlamaCppServerLLMClient() as llm_client:
    agent = MultiStepAgent(mode="direct", llm_client=llm_client, max_steps=3)
    result = agent.run(
        prompt="Suggest two design goals for a field-repairable drone battery latch.",
    )

print(result.final_output)
```

## Quickstart

Requires Python 3.12+.
Reproducible release installs are pinned to Python `3.12.12` (see `.python-version`).

```bash
python -m venv .venv
source .venv/bin/activate
make dev
make test
PYTHONPATH=src python3 examples/patterns/plan_execute.py
```

For frozen installs, optional extras, and release maintenance, see [Dependencies and Extras](https://cmudrc.github.io/design-research-agents/dependencies_and_extras.html).

## Examples

Start with [examples/README.md](https://github.com/cmudrc/design-research-agents/blob/main/examples/README.md) for runnable examples grouped by agents, clients, workflows, patterns, model selection, and tools.


## Docs

See the [documentation site](https://cmudrc.github.io/design-research-agents/) for the full guide set, including quickstart, backend setup, workflows, patterns, and API reference.

Build docs locally with `make docs`.

## Contributing

Contribution guidelines now live in [CONTRIBUTING.md](https://github.com/cmudrc/design-research-agents/blob/main/CONTRIBUTING.md).
