Skip to content

AGENTS.md

Latest commit

 

History

History
62 lines (49 loc) · 2.93 KB

AGENTS.md

File metadata and controls

62 lines (49 loc) · 2.93 KB

AGENTS.md

Python API client for the SoftwareONE Marketplace Platform (MPT) API. Provides synchronous (MPTClient) and asynchronous (AsyncMPTClient) clients built on httpx, with typed resource services, mixin-based HTTP operations, and an RQL query builder.

Documentation Reading Order

  1. README.md — repository overview, quick start, and documentation map
  2. docs/usage.md — installation, configuration, Python usage examples, and supported Docker-based commands
  3. docs/architecture.md — layered architecture, directory structure, and key abstractions
  4. docs/local-development.md — Docker-only setup and execution model
  5. docs/testing.md — repository-specific testing strategy and command mapping
  6. docs/contributing.md — repository-specific workflow and links to shared standards
  7. docs/documentation.md — repository-specific documentation rules

Then inspect the code paths relevant to the task:

  • mpt_api_client/mpt_client.py — public sync and async client entry points
  • mpt_api_client/http/ — HTTP clients, services, query state, and reusable mixins
  • mpt_api_client/resources/ — domain resource groups such as catalog, commerce, billing, and integration
  • mpt_api_client/models/ — response model layer and collection wrappers
  • mpt_api_client/rql/ — fluent RQL query builder
  • tests/unit/ — unit coverage for transport, resources, models, and query builder
  • tests/e2e/ — live API coverage by domain
  • make/ and compose.yaml — Docker-based local command entry points

API Reference

The upstream API contract is the MPT OpenAPI spec: https://api.s1.show/public/v1/openapi.json

Key Commands

Command Purpose
make build Build the Docker development environment
make test Run unit tests
make check Run all linting and type checks
make check-all Run checks + tests
make format Auto-format code
make bash Open a shell in the Docker container
make run Start an IPython session in Docker

Repository Rules

  • Prefer Docker-based make targets over ad hoc local Python commands.
  • Keep README.md concise and navigational.
  • Put topic-specific documentation under docs/ instead of expanding README.md.
  • Link shared engineering rules from mpt-extension-skills instead of duplicating them locally.

Project Structure

mpt_api_client/
├── mpt_client.py       # MPTClient / AsyncMPTClient entry points
├── http/               # HTTP transport, services, mixins
├── resources/          # API domain modules (catalog, commerce, billing, …)
├── models/             # Response model classes
├── rql/                # RQL query builder
└── exceptions.py       # Error hierarchy