Skip to content
Docs

Documentation navigation

Architecture

How the connector kernel layers fit together and where to extend.

#Architecture

Every connector — whether it talks to Slack or to your own internal API — needs the same plumbing: a way to authenticate, an HTTP client that retries and respects rate limits, an audit trail, and a way to test it without hitting the network. maivn-tools factors all of that into one shared kernel so each new connector is mostly a thin description of an API, not a re-implementation of the same infrastructure. This page shows how those pieces stack and where you would plug in your own.

maivn-tools is organized into small, single-purpose layers. Each layer can be imported and tested in isolation. Provider-specific connectors compose them rather than re-implementing infrastructure.

Plain text 
+--------------------------------------------------------+
|                Provider connectors (Tier 1+)           |
|  Gmail · Slack · GitHub · Postgres · ...               |
+--------------------------------------------------------+
|                 Generic adapters (Tier 1)              |
|  GenericHttpConnector · OpenAPIConnector ·             |
|  GraphQLConnector · WebhookListener · MCPBridge        |
+--------------------------------------------------------+
|                 Connector kernel (Tier 0)              |
|  core/ · auth/ · runtime/ · events/ · files/ ·         |
|  testing/                                              |
+--------------------------------------------------------+
|                       maivn SDK                        |
|  Agent · Swarm · MCPServer · events · hooks            |
+--------------------------------------------------------+

#Layers

#core

Stable data models and protocols every connector relies on.

  • ProviderMetadata — provider identity, supported auth modes, capability flags, and public scope catalog.
  • ConnectionMetadata and TokenMetadata — public, secret-free descriptions of a configured connection.
  • PermissionSet / PermissionFlag — least-privilege flags for each tool.
  • DryRunOutcome / DryRunPlan — the dry-run contract for write tools.
  • Connector, ToolProvider, and register_* helpers.

#auth

Auth strategies and secret resolvers. Strategies mutate request dictionaries in place; resolvers translate SecretRef values into the underlying string material.

Built-in strategies cover API keys (header or query), bearer tokens, HTTP Basic, and OAuth2 bearer tokens fed from a caller-supplied OAuth2TokenProvider. Built-in resolvers cover environment variables, a static in-memory map, and a chained resolver that walks a list.

#runtime

The portable HTTP client. Includes:

  • HttpTransport and the stdlib UrllibTransport.
  • HttpClient with retries, rate limits, default headers, correlation IDs, idempotency keys, and stable error normalization.
  • RetryPolicy (exponential backoff with full jitter).
  • TokenBucket for cooperative rate limiting.
  • Pagination helpers for cursor, offset, page-token, and delta-token patterns.
  • A stable exception hierarchy mapped from HTTP status codes.

#events

Audit events and webhook helpers.

  • AuditEvent and AuditSink model normalized audit trails.
  • WebhookVerifier and verify_hmac_signature validate provider webhook signatures.

#files

Provider-agnostic file primitives.

  • Attachment and AttachmentSource for normalized file references.
  • MIME detection (detect_mime_type, guess_mime_type, classify_kind).
  • TextExtractor plus a dependency-free UTF-8 extractor and a registry for optional extractors.
  • TransferProgress and TransferOutcome for bulk transfers.

#testing

MockTransport plugs into HttpClient and records every request the connector makes. Helpers json_response and text_response build canned responses for assertions.

#connectors

Concrete connectors built on the kernel:

  • connectors.generic_api — GenericHttpConnector, OpenAPIConnector, GraphQLConnector, WebhookListener.
  • connectors.mcp_bridge — declarative wrappers that build maivn.MCPServer instances at registration time.
  • connectors.files — sandboxed, read-only local-filesystem tools.

#Design principles

  • Public stability before breadth. A new provider must reuse the kernel rather than fork it.
  • Keep secrets out of public metadata. Auth describe() omits credential values. Application audit detail and provider errors need their own review.
  • Read-only by default. Destructive operations must declare themselves through permission flags and the destructive marker.
  • No required heavyweight dependencies. The HTTP transport uses the standard library. The package also requires the SDK, contracts, Pydantic, and artifact rendering libraries.
  • Composable with the SDK. Tools register through Agent.add_tool / Swarm.add_tool like any other callable; no custom runtime is required.