Server updates
The Socaity SDK keeps its installed client stubs in sync with the live catalog by calling update_package() when you import socaity, and again on the next import once a fifteen-minute cache has expired. This page explains the mechanism so you know what the SDK touches on disk, when it talks to the backend, and what to do if you publish or self-host a service.
SocaityServiceRegistry instantiates as a singleton when you import socaity. Its constructor calls update_package(), which POSTs to https://api.socaity.ai/v1/sdk/update_package, receives a diff of changed services, and rewrites the affected Python client stubs on disk. The cache TTL is fifteen minutes (CACHE_TTL_MINUTES = 15), so subsequent imports inside that window skip the network call. To force a refresh regardless of the TTL, call force_update_package() on the manager.
The SDK rewrites three directories inside the installed socaity package:
| Path | What lands there |
|---|---|
socaity/sdk/official/ | Reserved for services the backend flags as official. None ship in the hosted catalog today, so this directory is empty after install. Open-source services like face2face/speechcraft are self-hosted via APIPod, not managed here. |
socaity/sdk/community/ | Stubs for community-published services. |
socaity/sdk/replicate/<vendor>/ | Stubs for Replicate-backed services, grouped by vendor slug (for example black_forest_labs/flux_schnell.py). |
This is a runtime stub refresh, not a pip install. The wheel ships with a small snapshot of common stubs (only a handful of Replicate vendors are present on disk right after pip install socaity). update_package() keeps those installed stubs current as services change in the backend; to add a model that is not in your local snapshot, run socaity install <vendor>/<model> to generate its stub on demand.
from socaity.sdk.replicate.black_forest_labs import flux_schnell directly after update_package() has run. For anything else, run socaity install <vendor>/<model> (or socaity.install(...)) once to generate the stub, then import it. The stubs the SDK pulls come from the Socaity backend, which stores service metadata in a database. When the metadata changes there, the next update_package() call propagates the change into your local stubs. This section covers how the backend record itself gets created and updated, in case you publish your own service.
The database is the source of truth once a service has been registered. The service's openapi.json is the source of truth for endpoint parameter schemas only.
| Table | What it holds |
|---|---|
service_descriptors | Canonical metadata for a service: name, description, human-readable info. One row per logical service. |
service_hosting_information | Where and how a service is deployed. Multiple hosting records can exist per service (regions, providers, private deployments). |
service_endpoints | Endpoint metadata per service (name, description). Parameter schemas live in the service's openapi.json. |
service_categories | Many-to-many classification (Image Generation, Chat, Text-to-Image, and so on). |
ServiceFamily | Groups closely related variants under a shared family (for example, multiple Flux-Schnell deployments with minor differences). |
ServiceCollection | Curator-managed groupings (for example, all Meta/Facebook models). Many-to-many. |
model_descriptors | Documents the underlying AI model(s) backing a service. A service can use more than one model. |
When a service is first added to the platform, its openapi.json is the seed for the database record.
- Socaity populates the descriptor and endpoint metadata from the OpenAPI spec (docstrings and the APIPod
Appmetadata). - An LLM enrichment pass runs to standardise and improve the description.
- From that point on, the database is the ground truth. Descriptions can be edited directly. The
openapi.jsonis no longer the primary source for descriptive content. - Endpoint parameter schemas remain tied to
openapi.jsonat all times.
A new release of the source repository triggers an update. This differs from a re-upload. The change then propagates automatically to every public deployment linked to that repository.
- Socaity diffs the new
openapi.jsonagainst the current state. - An LLM merge pass reconciles the existing database description with any new information from the spec. The goal is to keep the richer of the two, not blindly overwrite.
- The merged result is written back to the database.
- The next time an SDK client calls
update_package()(on import, or after the fifteen-minute cache expires), the updated stub lands on disk.
| Scenario | What happens |
|---|---|
Identical openapi.json re-uploaded | Socaity asks whether to create a private deployment. If you decline, nothing is written. |
Modified openapi.json uploaded | Treated as an entirely new service. Socaity creates a fresh descriptor, hosting record, and endpoint rows from scratch. |
| Repository releases a new version | In-place update via the LLM merge flow. Propagates to all public deployments linked to the repo. |
| If you are | Then |
|---|---|
| Calling services from the SDK | Nothing to do. The next import (or the next refresh after fifteen minutes) picks up new and updated services. |
| Publishing a service from APIPod | Cut a new release of your repo to trigger an in-place update. A meaningfully modified spec re-uploaded by hand creates a new service instead. |
| Running a private deployment | Your copy is isolated from upstream changes. Re-deploy explicitly when you want a newer version. |
| Pinning to an exact catalog snapshot | Not currently exposed. The wheel ships a snapshot, but update_package() runs at import time. Disable it only by editing SocaityServiceRegistry directly, and accept that your stubs will drift. |
Socaity proxies third-party providers such as Replicate. Their URL shape and update behaviour differ from Socaity-hosted services.
| Provider | URL pattern |
|---|---|
| Socaity-hosted | services/{user_name}/{service_name}/{endpoint_name} |
| Replicate | services/third-party/replicate/{user}/{model}/predictions |
Third-party services are read-only on the Socaity side. You can call them, but Socaity cannot redeploy or rehost them.
service_data_readme.md in the Socaity backend repo. The client-side mechanism lives in socaity/core/socaity_service_registry.py. - Getting Started with APIPod: build a service, cut a release, watch the merge flow update the catalog entry.
- SocaitySDK CLI: status of the planned
socaityCLI surface and what is shipping today. - Install the SDK: install once with
pip install socaity; the stub snapshot ships with the wheel. - Job system: what a stub call actually returns and how to wait on it.