MPT-22057 mpt-api-python-client documentation fixes

[d3rky]

🤖 AI-generated PR — Please review carefully.

What

Documentation fixes for mpt-api-python-client (MPT-22057, under MPT-22048).

• docs/architecture.md: the models entry is model_collection.py / ModelCollection (not collection.py / Collection); add the exchange, integration, program, and spotlight resource domains to the tree; add StreamJSONLMixin and FilesOperationsMixin to the mixins table.
• docs/usage.md: list client.program and client.spotlight in the API surface, and note the timeout argument on from_config.
• README.md + AGENTS.md: add docs/unit_tests.md and docs/e2e_tests.md to the documentation map (they exist but were unlisted).

Findings not actioned (verified against code)

• AsyncService "stub": http/async_service.py defines a real AsyncService(ServiceBase), and the docs already describe it correctly — no change needed.
• docs/e2e.md / docs/migrations.md: not added — end-to-end docs already exist as e2e_tests.md, and the client has no migrations.

Testing

• audit_docs.py: no missing required docs.
• pre-commit hooks pass.

Subtask: MPT-22057 (parent MPT-22048).

Closes MPT-22057

• Updated architecture documentation to correct models entry from collection.py / Collection to model_collection.py / ModelCollection
• Added resource domains (exchange, integration, program, spotlight) to architecture documentation
• Added StreamJSONLMixin and FilesOperationsMixin to service-layer mixins table in architecture documentation
• Documented timeout parameter on MPTClient.from_config() method in usage documentation
• Added client.program and client.spotlight to API surface documentation
• Extended README.md and AGENTS.md documentation maps to include docs/unit_tests.md and docs/e2e_tests.md

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Organization UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 3d4197c0-5e75-4002-b247-52d5cca63a85

📥 Commits

Reviewing files that changed from the base of the PR and between 1d6ff11 and 338bd28.

📒 Files selected for processing (4)

• AGENTS.md
• README.md
• docs/architecture.md
• docs/usage.md

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• softwareone-platform/mpt-extension-skills (manual)

📜 Recent review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: build

🧰 Additional context used

📓 Path-based instructions (7)

docs/**/*.md

📄 CodeRabbit inference engine (docs/contributing.md)

When repository behavior changes, update the narrowest relevant document under docs/

Files:

• docs/usage.md
• docs/architecture.md

docs/*.md

📄 CodeRabbit inference engine (docs/documentation.md)

docs/*.md: Topic-specific documentation must live in the matching file under docs/ directory
Shared engineering rules must be linked from mpt-extension-skills instead of copied into this repository

Put topic-specific documentation under docs/ instead of expanding README.md

Files:

• docs/usage.md
• docs/architecture.md

docs/usage.md

📄 CodeRabbit inference engine (docs/documentation.md)

docs/usage.md is the source of truth for installation, configuration, examples, and supported command entry points

Files:

• docs/usage.md

**/*

⚙️ CodeRabbit configuration file

**/*: For each subsequent commit in this PR, explicitly verify if previous review comments have been resolved

Files:

• docs/usage.md
• README.md
• AGENTS.md
• docs/architecture.md

docs/**

⚙️ CodeRabbit configuration file

docs/**: Review documentation changes against docs/documentation.md and the linked repository's standards/documentation.md.
Use those documents as the source of truth for structure, topic boundaries, navigation updates, and when to link shared rules instead of copying them.

Files:

• docs/usage.md
• docs/architecture.md

---

⚙️ CodeRabbit configuration file

docs/**: # Architecture

This document describes the internal architecture of mpt-api-python-client.

Overview

mpt-api-python-client is a Python API client that provides a typed, fluent interface for the
SoftwareONE Marketplace Platform (MPT) REST API. It supports both synchronous and asynchronous
usage and is built on top of httpx.

API Reference: The full upstream API contract is described by the
MPT OpenAPI Spec.
The client mirrors this spec's resource structure.

The client exposes every MPT API domain (catalog, commerce, billing, etc.) as a resource group,
where each resource is a service object composed from reusable HTTP operation mixins.

Directory Structure

mpt_api_client/
├── __init__.py              # Public API: MPTClient, AsyncMPTClient, RQLQuery
├── mpt_client.py            # Client entry points
├── constants.py             # Shared constants (content types)
├── exceptions.py            # Error hierarchy (MPTError, MPTHttpError, MPTAPIError)
│
├── http/                    # HTTP transport layer
│   ├── client.py            # Sync HTTPClient (httpx.Client)
│   ├── async_client.py      # Async AsyncHTTPClient (httpx.AsyncClient)
│   ├── base_service.py      # ServiceBase — shared service logic
│   ├── service.py           # Service — sync service (extends ServiceBase)
│   ├── async_service.py     # AsyncService — async service (extends ServiceBase)
│   ├── query_state.py       # Query parameter accumulation
│   ├── client_utils.py      # URL validation helpers
│   ├── types.py             # Type aliases (Response, HeaderTypes, etc.)
│   └── mixins/              # Composable HTTP operation mixins
│       ├── collection_mixin.py
│       ├── create_mixin.py
│       ├── create_file_mixin.py
│       ├── update_mixin.py
│       ├── update_file_mixin.py
│       ├── delete_mixin.py
│       ├── get_mixin.py
│       ├── enable_mixin.py
│       ├── disable_mixin...

Files:

• docs/usage.md
• docs/architecture.md

**

⚙️ CodeRabbit configuration file

**: # AGENTS.md

Working protocol for any task in this repository:

1. Identify the task type and select only the local repository files that are relevant to that task.
2. Read only those relevant local files before making changes.
3. If any selected local file references shared standards or shared operational guidance that are relevant to the same task, read those shared documents too before proceeding.
4. Treat repository-local documents as repository-specific additions, restrictions, or overrides to shared guidance.
5. If a repository-local rule conflicts with a shared rule, the local repository rule takes precedence.

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

When applicable, read the repository documentation in this 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 ...

Files:

• docs/usage.md
• README.md
• AGENTS.md
• docs/architecture.md

README.md

📄 CodeRabbit inference engine (AGENTS.md)

Keep README.md concise and navigational

Files:

• README.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: Identify the task type and select only the local repository files that are relevant to that task before making changes

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: Read relevant local files before making changes, and if selected files reference shared standards or operational guidance, read those shared documents too before proceeding

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: Treat repository-local documents as repository-specific additions, restrictions, or overrides to shared guidance

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: If a repository-local rule conflicts with a shared rule, the local repository rule takes precedence

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: Prefer Docker-based `make` targets over ad hoc local Python commands

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:05.212Z
Learning: Link shared engineering rules from `mpt-extension-skills` instead of duplicating them locally

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:17.346Z
Learning: Client architecture should be organized in four layers: Client (entry point), Resource Groups (domains), Service + Mixins (HTTP operations), and HTTPClient (httpx transport)

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:17.346Z
Learning: Services should mirror the MPT OpenAPI Spec's resource structure and expose every MPT API domain as a resource group

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:25.792Z
Learning: Install the mpt-api-client package using `pip install mpt-api-client` or `uv add mpt-api-client`

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:25.792Z
Learning: Require Python 3.12+ for the mpt-api-client library

Learnt from: CR
Repo: softwareone-platform/mpt-api-python-client

Timestamp: 2026-06-11T13:53:25.792Z
Learning: Configure MPT API client using environment variables `MPT_API_BASE_URL` and `MPT_API_TOKEN`

🔇 Additional comments (7)

AGENTS.md (1)

26-27: LGTM!

README.md (1)

18-19: LGTM!

docs/architecture.md (3)

53-53: LGTM!

---

63-68: LGTM!

---

136-137: LGTM!

docs/usage.md (2)

60-61: LGTM!

---

120-121: LGTM!

---

📝 Walkthrough

Walkthrough

This PR updates four documentation files to reflect the current state of the MPT API Python client library. Test documentation pointers are added to reading-order guides, architecture documentation is refreshed with updated model naming and expanded resources, and usage documentation is extended with timeout configuration and new resource groups.

Changes

Documentation Refresh

Layer / File(s)	Summary
Documentation reading order AGENTS.md, README.md	Test documentation files (docs/unit_tests.md and docs/e2e_tests.md) added to the recommended reading sequence in both the agent guide and developer setup documentation.
Architecture documentation refresh docs/architecture.md	Model directory now documents model_collection.py instead of collection.py. Resources inventory expanded with exchange, integration, program, and spotlight groups. Service mixins table extended with StreamJSONLMixin and FilesOperationsMixin. Formatting adjustment applied.
Usage documentation extension docs/usage.md	MPTClient.from_config() documented to accept timeout parameter (default 60.0 seconds). API surface list extended to include client.program and client.spotlight resource groups.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• softwareone-platform/mpt-api-python-client#310: Updates AGENTS.md documentation reading order to add new documentation files to the recommended sequence.
• softwareone-platform/mpt-api-python-client#254: Modifies repository documentation entry points including AGENTS.md and README.md documentation reading order with pointers to testing-related docs.
• softwareone-platform/mpt-api-python-client#299: Touches documentation structure, particularly docs/usage.md, which is extended in this PR with new configuration and resource-group documentation.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Pr And Commit Formatting	✅ Passed	PR title uses MPT-22057 format, description explains changes, commit follows Conventional Commits (docs: ...), has detailed body explaining what changed and why, single commit, and linear history w...
Documentation Up To Date	✅ Passed	All code/behavior changes have matching documentation updates: architecture.md documents model_collection.py, new resources, and mixins; usage.md documents timeout param and new client properties;...

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud