SocAIty SDK

Build AI-powered applications with ease

socaity SDK talks to the socaity.ai catalog and gate.
Catalog jobs via client.run. Agents and workflows have their own verbs. Hosted in the EU, or on your own hardware.

Quickstart · Why this · Features · Compose models · LangChain · Model zoo · Ecosystem

Quickstart

Two steps. Under five minutes. You get any LLM running or an audio file on disk.

from socaity import client

job = client.run("speechcraft/text2voice", text="Welcome to generative AI", voice="hermine")
job.get_result().save("welcome.mp3")

That is the whole pattern: name the service and endpoint, pass params, save the result.

socaity run speechcraft/text2voice --text "Welcome to generative AI"

Authentication. We support CLI Login, but for production environment we recommend to set the API key as environment variable.

pip install socaity
export SOCAITY_API_KEY=sk-...   # free key at socaity.ai

Why socaity SDK

Real applications chain models: LLM → image → speech → video. Raw HTTP, per-provider SDKs, and hand-rolled polling make that slow and brittle.

Why not just use fastSDK? You can. fastSDK connects to any OpenAPI, APIPod, RunPod, or Replicate service. socaity SDK adds catalog resolve, client.run, and session credentials so you skip spec hunting for every model.

Why not OpenRouter or Replicate alone? Both are pay-per-call model catalogs. Neither gives you deployment, workflow orchestration, or EU-sovereign hosting. socaity combines MaaS, deployment, and agentic workflows in one stack. The SDK is your entry point to all of it.

Key features

Import and call. Name the catalog slug and endpoint. No GPU setup, no REST boilerplate.

Parallel by default. Every call returns a job immediately. Run ten models at once, collect results when you need them.

from socaity import client

llm_job = client.run("deepseek-v3", prompt="Write a haiku about SDKs.")
img_job = client.run("black-forest-labs-flux-schnell/predictions", prompt="A robot at sunset in the Alps.")
text, images = llm_job.get_result(), img_job.get_result()

Catalog jobs. client.run("speechcraft/text2voice", text="hello") or client.connect("speechcraft").submit_job("/text2voice", text="hello"). Slug on the URL. details_id on the query. Agents: client.run_agent. Workflows: client.run_workflow.

Switch models without rewriting. Want to try another model? No need to rewrite your code-base just switch the call. Having a local model? Point at it at use it likewise from the same sdk.

EU-first platform. Socaity runs on European infrastructure (Scaleway PAR-1), Models run where you choose. Data stays in the EU. Workflows are traceable. Pricing is predictable.

Compose models

No single model covers a real task. The SDK is built for composition.

from socaity import client

poem = client.run(
    "deepseek-v3",
    prompt="Three sentences on why an SDK beats raw HTTP.",
).get_result()

client.run("speechcraft/text2voice", text="".join(poem), voice="hermine").get_result().save("poem.mp3")

client.run(
    "black-forest-labs-flux-schnell/predictions",
    prompt="A robot at sunset in the Alps, cinematic anime, 4k.",
    num_outputs=1,
).get_result()[0].save("poem.png")

https://github.com/user-attachments/assets/978ee377-3ceb-4a87-add5-daee15306231

Jobs vs. results

Calls return a job handle, not a blocked connection. Poll when ready, cancel when not, run hundreds in parallel. Agent turns use client.run_agent. Workflow runs use client.run_workflow. To cut in on a live agent turn, pass supersedes_job_id so the previous job is interrupted and settled before the next POST.

job = client.run("deepseek-v3", prompt="What a time to be alive.")
# ... other work ...
result = job.get_result()

Price estimate. Before you submit, ask for predicted cost and runtime (Socaity-hosted services):

from socaity import client

estimate = client.connect("black-forest-labs-flux-schnell").estimate(
    "/predictions", prompt="a lighthouse at sunset"
)
print(estimate.estimated_price_eur, estimate.estimated_inference_time_s)

Streaming. Schema endpoints (chat, TTS, video) accept stream=True. Iterate live tokens or bytes, or let get_result() assemble the full payload when you skip streaming.

job = deepseek_v3()(messages=[{"role": "user", "content": "Hello"}], stream=True)
for chunk in job.stream():
    print(chunk, end="", flush=True)

Under the hood, fastSDK orchestrates requests through meseex, a lightweight job runtime for async I/O, parallel execution, and streaming.

LangChain

You already build agents with LangChain or LangGraph. ChatSocaity is a LangChain chat model that talks to any Socaity or APIPod chat service: a hosted model slug, a catalog service id, or a local URL while you develop.

Install LangChain separately (pip install langchain-core). The socaity package does not pull it in.

from langchain.agents import create_agent
from socaity.integrations.langchain import ChatSocaity

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model=ChatSocaity(model="Qwen3.6-27B-FP8"),
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)

result = agent.invoke({"messages": [{"role": "user", "content": "What's the weather in San Francisco?"}]})
print(result["messages"][-1].content_blocks)

You can immediately use the model for chatting

from langchain_core.messages import HumanMessage
from socaity.integrations.langchain import ChatSocaity

model = ChatSocaity(model="socaity-model-slug")  # Go to the MaaS catalog to find your service.

answer = model.invoke([HumanMessage("Summarize why an SDK beats raw HTTP in one sentence.")])
print(answer.text)

Stream token by token, bind tools, or force a specific function with tool_choice. Conversation history, tool round trips, reasoning blocks, and usage metadata work the same way as with other LangChain chat models. For LangGraph and checkpointers you change nothing on the model side: persist graph state outside the model as you already do.

for chunk in model.stream([HumanMessage("What color is the sky?")]):
    print(chunk.text, end="", flush=True)

def get_weather(location: str) -> str:
    """Current weather for a city."""
    return "sunny"

bound = model.bind_tools([get_weather])
ai = bound.invoke([HumanMessage("Weather in Boston?")])

Hosted service on socaity.ai, or your own APIPod instance on localhost: same API. See test/test_langchain_chat.py for the full matrix (plain, serverless, tools, streaming).

Real-world use

Game developers building AI NPCs: generate dialogue with an LLM, synthesize speech, clone a voice, drive facial animation. Four models, one Python script.

Content creators automating video pipelines: generate a thumbnail with text-to-image, swap faces in footage, add a voice-over with text-to-speech.

SMEs replacing agency workflows: marketing copy, product images, and localized audio from one codebase, without a dedicated ML team.

More patterns on our docs or on socaity.ai.

Model zoo

The catalog lives at socaity.ai. Install any listed model into your local SDK:

socaity -i model_name_or_id

Representative domains available today:

New models land frequently. Catalog reads hit the live backend. There is no local generated-client sync.

Browse the full list, pricing, and API keys at socaity.ai.

Authentication

Set your API key as an environment variable. This keeps secrets out of source control.

export SOCAITY_API_KEY=sk-...

You can pass api_key= directly in code for local experiments, but do not commit it.

from socaity import Client
client = Client(api_key=os.getenv("SOCAITY_API_KEY"))

Hosted, local, or hybrid

Any fastSDK-compatible service (OpenAPI, APIPod, RunPod, Replicate) works with this package. Override the service address in the registry when you need a custom backend.

Publish an APIPod service to socaity.ai and it appears in the catalog. Public services can earn platform credits.

Ecosystem

Three packages, one pipeline:

Build a service with APIPod. Consume it with fastSDK. Import it from socaity when it is in the catalog.

socaity.ai ties deployment, MaaS, and agentic workflows (SPAINE) into one EU-sovereign platform. The SDK is how developers access the model layer today.

Documentation

Deep architecture docs for fastSDK and APIPod live in each repo's TECHNICAL_README.md. The README here stays focused on getting you to a first result.

Status

Alpha. Syntax and APIs will change. Pin your version in production. We ship fast because the catalog and capabilities grows fast.

Contribute

Issues and pull requests welcome.

git clone https://github.com/SocAIty/socaity.git
cd socaity
pip install -e ".[dev]"
pytest

License

GPL-3.0. See LICENSE.txt.

Made with ❤️ by SocAIty