Metadata-Version: 2.4
Name: design-research-agents
Version: 0.3.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: PyYAML<7,>=6.0.2
Provides-Extra: dev
Requires-Dist: mypy<2,>=1.10; extra == "dev"
Requires-Dist: pydata-sphinx-theme<1,>=0.16; 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: sphinx-copybutton<1,>=0.5; extra == "dev"
Requires-Dist: sphinxcontrib-mermaid<2,>=1.0; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Provides-Extra: azure
Requires-Dist: openai<2,>=1.40; extra == "azure"
Provides-Extra: openai
Requires-Dist: openai<2,>=1.40; extra == "openai"
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: memory-chroma
Requires-Dist: chromadb<2,>=1.0; extra == "memory-chroma"
Provides-Extra: memory-graph
Requires-Dist: networkx<4,>=3.0; extra == "memory-graph"
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: 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: mlx
Requires-Dist: mlx-lm>=0.14; (platform_system == "Darwin" and platform_machine == "arm64") and extra == "mlx"
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"
Requires-Dist: vllm<1,>=0.6; (platform_system == "Linux" and python_version < "3.14") and extra == "local"
Requires-Dist: sglang<1,>=0.4; (platform_system == "Linux" and python_version < "3.14") and extra == "local"
Provides-Extra: providers
Requires-Dist: anthropic<1,>=0.40; extra == "providers"
Requires-Dist: google-genai<2,>=1.0; extra == "providers"
Requires-Dist: groq<2,>=1.0; extra == "providers"
Requires-Dist: openai<2,>=1.40; extra == "providers"
Provides-Extra: full
Requires-Dist: anthropic<1,>=0.40; extra == "full"
Requires-Dist: google-genai<2,>=1.0; extra == "full"
Requires-Dist: groq<2,>=1.0; 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: openai<2,>=1.40; 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/examples.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/examples.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)

<!-- release-callout:start -->
> [!IMPORTANT]
> Current monthly release: [Lovelace Lift - May 2026](https://github.com/cmudrc/design-research-agents/milestone/3)  
> Due: May 1, 2026  
> Tracks: April 2026 work
<!-- release-callout:end -->

`design-research-agents` is the agent-execution layer in the cmudrc design
research ecosystem.

It provides typed, composable contracts for direct calls, multi-step runs,
workflow orchestration, tool execution, and traceable experimentation.

## Overview

This package centers on reproducible agent workflows with a compact public API:

- Two primary entry points: `DirectLLMCall` and `MultiStepAgent` (`direct`, `json`, and `code` modes)
- A seeded random control-condition agent for packaged-problem studies (`SeededRandomBaselineAgent`)
- A prompt-driven workflow agent for packaged-problem studies (`PromptWorkflowAgent`)
- Workflow primitives for model, tool, delegate, loop, and memory steps
- A tool runtime built around `Toolbox`, with callable, script, and MCP-backed tool configs
- Hosted and local LLM clients, plus `ModelSelector` for backend-selection policies
- Prebuilt coordination and reasoning patterns for plan/execute, propose/critic, debate, routing, round-based coordination, blackboard, tree search, Ralph loops, nominal teams, RAG, and conversation
- Tracing, structured `ExecutionResult` outputs, and runnable examples aimed at repeatable experiments

## 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 target Python `3.12` (see `.python-version`).

If you prefer a guided editor-first flow, use the
[VS Code Setup Guide](https://cmudrc.github.io/design-research-agents/vscode_setup.html).
It walks through creating a virtual environment, installing the published
package, and running a first script in VS Code.

```bash
python -m venv .venv
source .venv/bin/activate
make dev
make test
PYTHONPATH=src python examples/agents/direct_llm_call.py
```

The base-install path uses `OpenAICompatibleHTTPLLMClient` and expects a running
OpenAI-compatible endpoint. Contributor setup (`make dev`) installs development
tooling only; backend runtimes are explicit extras.

For frozen installs, 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 [published documentation](https://cmudrc.github.io/design-research-agents/)
for quickstart guidance, backend setup, workflow/pattern guides, and API docs.

Build docs locally with:

```bash
make docs
```

## Public API

The supported public surface is whatever is exported from
`design_research_agents.__all__`.

Top-level exports include:

- Agent entry points: `DirectLLMCall`, `MultiStepAgent`, `SeededRandomBaselineAgent`, `PromptWorkflowAgent`
- Core contracts: `ExecutionResult`, `LLMRequest`, `LLMMessage`, `LLMResponse`, `ToolResult`
- Workflow runtime: `Workflow`, `CompiledExecution`, and step contracts for model/tool/delegate/loop/memory behavior
- Tools: `Toolbox`, `CallableToolConfig`, `ScriptToolConfig`, `MCPServerConfig`
- Patterns: conversation, debate, plan/execute, propose/critic, Ralph loops, nominal teams, routing, round-based coordination, blackboard, tree search, and RAG
- LLM clients: hosted and local adapters, including OpenAI-compatible HTTP plus provider-specific clients
- Runtime services: `ModelSelector` and `Tracer`

## Contributing

Contribution workflow and quality gates are documented in
[CONTRIBUTING.md](https://github.com/cmudrc/design-research-agents/blob/main/CONTRIBUTING.md).
