Device-package integration contract (reproducibility specification)

This document is a contract for future developers and AI assistants to reproduce the same architecture, without inventing requirements or claiming unimplemented integration work is complete.

Invariants

  1. The single common DeviceProxy is a factory, not a transport abstraction. It looks up a callable by device-class name and forwards all arguments unchanged.

  2. Device-class names are unique. Reject duplicates; never use (device_class, transport) composite keys.

  3. Each device package provides dedicated clients. Use actual classes such as AsyncCobottaClient and SyncCobottaClient; do not invent a CobottaClient class.

  4. Async/sync selection belongs in a registered factory. make_async_sync_factory is an optional helper for HTTP/gRPC pairs. Do not force Tango to use it.

  5. Preserve device-specific constructor arguments. The common factory must not interpret or fill config, api_spec, addresses, etc.

  6. No auto-discovery: no entry_points, package enumeration, database, or network discovery. Users explicitly import/initialize known device packages.

  7. Preserve existing single-device usage: direct client instantiation, package-local proxy, and common proxy are all valid.

  8. Keep transport frameworks independent. The common package must not import HTTP/gRPC/Tango; transport and dispatch stay in their frameworks.

  9. Do not claim .pyi integration is complete. It remains open work.

Implementation procedure

  1. Inspect the actual source to identify device class, dedicated client classes, and constructor signatures.

  2. Define a callable to instantiate dedicated clients. Existing async/sync pairs may use make_async_sync_factory.

  3. Register with register_device_proxy("UniqueDeviceClass", creator) during explicit package import or initialization.

  4. Test creating at least two distinct device classes in the same process via the common DeviceProxy.

  5. Verify existing direct-client and package-local proxy usage still works.

  6. Separately test real transport integration and .pyi generation; record untested items explicitly.

  7. Update Japanese and English README/Pages documentation together.

Prohibited deviations

  • Adding a register_backend transport registry.

  • Registering one device-class name separately per transport.

  • Giving the common DeviceProxy built-in semantics for async_mode or config.

  • Claiming that pip install alone automatically resolves device names.

  • Replacing existing async/sync client classes with an invented unified class.

Implemented API

register_device_proxy(device_class, creator), DeviceProxy(device_class, *args, **kwargs), create_device_proxy(device_class), get_device_proxy_entry(device_class), list_device_proxies(), unregister_device_proxy(device_class), make_async_sync_factory(...).

This contract covers the current common-factory prototype. Migration of existing device packages and integration of type-stub generation remain undecided.