apipod_registry

Parse, hold and persist Services. This package is the one-stop tool for managing AI service information: it turns raw specs into typed contracts and keeps services, models and categories in one registry.

Built on socaity-schemas: Service is the aggregate root, each ServiceDetails binding carries a ServiceContract (the machine-readable interface parsed from OpenAPI or Cog).

What it does

• parse_contract(spec): OpenAPI, APIPod, Cog and MCP (tools/list) documents become a ServiceContract with typed operations, parameters, streaming flags and a specification_hash. Every operation gets a unique operation_key: a normalized OpenAPI operationId (create-image), else {method}-{path tokens} (get-users-by-id), else the MCP tool name.
• resolve_operation(service, details, operation): the one operation lookup. Accepts a catalog endpoint id, an operation_key, a provider operation_id, or an HTTP path owned by exactly one operation; without operation the first public operation wins. Aliases are resolved at runtime, never stored. active_details(service) returns details[0], the binding unpinned calls use (the catalog orders details active first).
• materialize_contract(spec, provider): parse_contract plus provider wire behavior. Replicate wraps every cog model in its predictions job API, so contracts of replicate deployments get has_job_queue=True here, not in the parsers.
• parse_address(url): URLs become typed ServiceAddress objects (socaity, RunPod, Replicate, generic).
• create_service(contract, address): the minimal Service, one details binding, ready to register.
• credential_requirements(contract): security scheme names a caller must supply, contract-wide and per endpoint. Parsers keep securitySchemes and security on the contract so clients place credentials at send time.
• Registry: in-memory catalog with id/name lookups for services, models and categories. Attach a ServiceStore for persistence; a cache miss reads through store.load, load_all() warms the whole cache. Included stores: FileSystemStore (local JSON) and CatalogStore (read-only, over the platform catalog API; pass a socaity-cli CatalogClient). The platform backend ServiceCatalog owns service data; this package never talks to a database.

Usage

from apipod_registry import parse_contract, create_service, Registry, FileSystemStore

contract = parse_contract(openapi_dict)
service = create_service(contract, address="https://api.socaity.ai/services/v1/abc123")

registry = Registry(service_store=FileSystemStore())
registry.load_all()
registry.add_service(service)

registry.get_service("abc123")            # by id
registry.get_service("face2face")         # by name
registry.get_operation("face2face", "swap")  # operation key, operation id or unique path

Two axes that stay separate by design: contract.specification says how the spec is written (openapi, apipod, cog, cog2, mcp), details.deployment.provider (or a connector address) says where it runs, details.execution says who provisions it (provisioned, mediated, external, platform). A Cog model hosted on Replicate is specification="cog" and deployment.provider="replicate".

MIT-licensed.