Minimal Radical Agent API

A systematic requirements set for a minimal, practical API useful for today's agents while supporting future radical upgrades.

Project Structure

project_002/
├── README.md              # This file
├── docs/                  # Documentation
│   ├── requirements_collection_plan.md
│   ├── user_stories_and_use_cases.md
│   ├── minimal_api_*.md
│   └── provider_selection/  # Provider selection docs
│       └── minimal_api/
│           ├── README.md
│           ├── INTEGRATION.md
│           ├── HUMAN.md
│           ├── agent-personas.md
│           └── key-version.md
├── spec/                  # API Specifications
│   ├── openapi_optimization_api.yaml
│   └── provider_selection/
│       └── minimal_api/
│           ├── system.spec.md
│           ├── algorithm.spec.md
│           ├── tests.spec.md
│           ├── auth.spec.md
│           ├── personas.spec.md
│           └── src/         # Implementation
│               ├── models.py
│               ├── engine.py
│               └── test_provider_selection.py
├── src/
│   └── py/
│       ├── api.py
│       └── provider_selection/  # Provider selection module
│           ├── __init__.py
│           ├── providers.py
│           └── selector.py
├── tests/                 # Test Artifacts
│   ├── validation/
│   ├── responses/
│   ├── audit/
│   ├── integration/
│   └── *.json
└── human_aspects/         # (legacy, contents moved to docs/)

Quick Start

1. Read the requirements: docs/requirements_collection_plan.md
2. Review user stories: docs/user_stories_and_use_cases.md
3. Check test artifacts: tests/README.md
4. Review API spec: spec/openapi_optimization_api.yaml
5. Provider selection spec: spec/provider_selection/minimal_api/
6. Run tests: cd spec/provider_selection/minimal_api/src && python3 -m pytest test_provider_selection.py -v project_002/ ├── README.md # This file ├── docs/ # Documentation │ ├── requirements_collection_plan.md │ ├── user_stories_and_use_cases.md │ ├── minimal_api_*.md │ └── provider_selection/ # Provider selection docs │ ├── README.md │ └── minimal_api/ │ ├── INTEGRATION.md │ ├── HUMAN.md │ ├── agent-personas.md │ └── key-version.md ├── spec/ # API Specifications │ ├── minimal_api_first_draft.yaml │ └── openapi_optimization_api.yaml ├── src/ │ └── py/ │ ├── api.py │ └── provider_selection/ # Provider selection module │ ├── init.py │ ├── providers.py │ └── selector.py ├── tests/ # Test Artifacts │ ├── validation/ │ ├── responses/ │ ├── audit/ │ ├── integration/ │ └── *.json └── human_aspects/ # (legacy, contents moved to docs/)

## Quick Start

1. **Read the requirements**: `docs/requirements_collection_plan.md`
2. **Review user stories**: `docs/user_stories_and_use_cases.md`
3. **Check test artifacts**: `tests/README.md`
4. **Review API spec**: `spec/openapi_optimization_api.yaml`
5. **Provider selection**: `docs/provider_selection/README.md`
6. **Agent personas & API keys**: `docs/provider_selection/minimal_api/`

## Test Execution

```bash
cd tests
# Run validation tests
python3 -c "import json; json.load(open('validation/request_validation_cases.json'))"

Status

• ✅ Requirements collection complete
• ✅ 97+ test cases defined
• ✅ User stories for human and autonomous agents
• ✅ API specifications drafted
• ✅ Provider selection system implemented (13 tests passing)