__init__.py 2.8 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273
  1. """Connector tool-gateway package: typed client-side plumbing for remote tools.
  2. This package owns everything hermes-agent needs to talk to the managed tool
  3. gateway's connector routes (search / schemas / execute / connections) and to
  4. merge remote execute results back into ``tool_call`` result arrays.
  5. Layering rules (enforced by review, not imports — keep them true):
  6. - ``wire.py`` is a leaf: pydantic v2 models for the four gateway routes plus
  7. route path constants. No pydantic model may escape the wire/client layer;
  8. everything above sees plain dicts and frozen dataclasses.
  9. - ``errors.py`` is stdlib-only: the ``ToolGatewayError`` family, the ONE
  10. gateway error-envelope parser, and the single producer of the
  11. connection-required payload shown to the model.
  12. - ``names.py`` is stdlib-only: the ``connectors__<connector>__<tool>`` name
  13. codec. Parsing never raises — a malformed name is a per-entry error and
  14. sibling calls still run.
  15. - ``config.py``: the ``tools.connectors`` config gate. Availability fails
  16. closed: config flag AND the managed Nous tools entitlement.
  17. - ``merge.py`` is PURE: partition / splice / render with no I/O and no
  18. exceptions. Position in the original ``calls[]`` array is the only
  19. correlation key — the wire ``index`` field is never trusted.
  20. - ``client.py`` / ``bridge.py``: the HTTP client and the only module core
  21. imports. Every bridge entry point is TOTAL — it catches its own
  22. exceptions, because the bridge branch bypasses the registry's catch-wrap.
  23. Approval is settled by the core BEFORE the bridge is called; denied
  24. entries never reach it.
  25. Core reaches this package through ``tools.connectors.dispatch.py``, which
  26. dispatches one gateway request per connector entry via ``bridge.run_remote``
  27. and re-enters core dispatch for each entry so per-tool policy fires against
  28. the composed ``connectors__`` name.
  29. """
  30. from tools.connectors.gateway.config import (
  31. MAX_CALLS_PER_DISPATCH,
  32. ConnectorConfig,
  33. connectors_available,
  34. )
  35. from tools.connectors.gateway.errors import (
  36. GatewayAuthError,
  37. GatewayUnavailable,
  38. IdempotencyConflict,
  39. ToolGatewayError,
  40. parse_gateway_error,
  41. render_connection_required,
  42. )
  43. from tools.connectors.gateway.names import (
  44. CONNECTOR_BATCH_SENTINEL,
  45. CONNECTOR_NAME_PREFIX,
  46. ConnectorName,
  47. format_connector_name,
  48. is_connector_name,
  49. parse_connector_name,
  50. )
  51. __all__ = [
  52. "CONNECTOR_BATCH_SENTINEL",
  53. "CONNECTOR_NAME_PREFIX",
  54. "MAX_CALLS_PER_DISPATCH",
  55. "ConnectorConfig",
  56. "ConnectorName",
  57. "GatewayAuthError",
  58. "GatewayUnavailable",
  59. "IdempotencyConflict",
  60. "ToolGatewayError",
  61. "connectors_available",
  62. "format_connector_name",
  63. "is_connector_name",
  64. "parse_connector_name",
  65. "parse_gateway_error",
  66. "render_connection_required",
  67. ]