feat: add public Files API methods

[HareeshBahuleyan]

Why

The gateway Files API exists, but callers have to reach into the generated client because the supported SDK shell does not expose it.

What changed

Added sync and async methods to upload, list, retrieve, download, and delete files. Multipart uploads and binary downloads use raw HTTP transport, with SDK error mapping, documentation, and unit coverage.

Notes

• The Files API is currently available on standalone Otari gateways.
• Verified with 150 passing tests, Ruff, strict mypy, and package builds on Python 3.12.
• Implemented with Pi using OpenAI gpt-5.6-sol.

Ref: mozilla-ai/otari#177

[Copilot]

🟡 Changes recommended

The canonical endpoint manifest must classify the newly wrapped Files endpoints as covered.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds public synchronous and asynchronous Files API support to the SDK shell.

Changes:

• Adds upload, list, retrieve, download, and delete methods.
• Uses raw HTTP for multipart uploads and binary downloads.
• Adds documentation and unit coverage.

File summaries

File	Description
src/otari/client.py	Adds synchronous Files API methods.
src/otari/async_client.py	Adds asynchronous Files API methods.
tests/unit/test_client.py	Tests synchronous file operations.
tests/unit/test_async_client.py	Tests asynchronous file operations.
README.md	Documents Files API usage.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[HareeshBahuleyan]

Follow-up from reviewing PR head dd0ae0c against SDK main 784676d and the local gateway checkout at bd0ea901.

Findings to address before merging

1. P1: List, retrieve, and delete crash after merging current main. The generated FilesApi now exposes files_list_files, files_get_file, and files_delete_file, but both clients call the old generated names. A temporary merge reproduces AttributeError for all three operations in both clients; mypy reports six matching errors.

   • Locations at PR head: src/otari/client.py:469,486,510 and src/otari/async_client.py:445,462,486.
   • Fix: update the six calls to the current generated names. Update the new tests from /v1/files to /api/v1/files too; current main already corrects the raw transport prefix.

2. P2: File listings silently stop at 100 items with no continuation available. The current gateway defaults to 100 results and returns has_more, first_id, and last_id. Both wrappers discard that metadata and accept neither after nor limit. Callers cannot discover older files through the public SDK once they exceed one page.

   • Locations at PR head: src/otari/client.py:461–476 and src/otari/async_client.py:437–452.
   • Verified: a response containing has_more=True becomes a plain 100-item list; passing after raises TypeError in both clients.
   • Fix: expose pagination parameters and retain page metadata, or implement automatic pagination. Add multi-page tests for sync and async clients.

Gateway alignment

The five operations otherwise match the current gateway contract: multipart upload, metadata listing/retrieval, binary download, and deletion. User/workspace scoping remains server-enforced. Standalone-only documentation is still appropriate: Files routes are absent from hybrid and hosted modes.

The resolved manifest comment needs no further action in this SDK PR. The gateway copies one canonical manifest into all four SDK repositories, so marking Files endpoints universally covered would overstate shell coverage before the cross-SDK rollout.

Verification

• Original PR head: 150 unit tests passed.
• Temporary merge with current main: 139 passed, 12 failed. Six failures are obsolete generated calls; six are stale URL mocks.
• Merged-tree Ruff passed; mypy reported six errors.
• Reviewed SDK-to-gateway code paths and reproduced the issues locally. No live gateway/database/storage round trip was run. Neither checkout was changed.