fastsdk 0.2.32__tar.gz → 0.3.1__tar.gz

{fastsdk-0.2.32 → fastsdk-0.3.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: fastsdk
-Version: 0.2.32
-Summary: Your SDK and model zoo for generative AI. Build AI-powered applications with ease.
+Version: 0.3.1
+Summary: Turn any AI/web service (OpenAPI, Replicate, RunPod, APIPod) into a native-feeling Python client.
 Author: SocAIty
 License:                     GNU GENERAL PUBLIC LICENSE
                                Version 3, 29 June 2007
@@ -692,117 +692,175 @@ Requires-Dist: singleton_decorator==1.0.0
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: fastcloud>=0.0.14
 Requires-Dist: apipod-registry>=0.0.2
+Requires-Dist: socaity-schemas>=0.0.1
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
+Provides-Extra: replicate
+Requires-Dist: replicate; extra == "replicate"
 Dynamic: license-file
 
+<p align="center">
+  <img src="docs/assets/banner.png" alt="fastSDK. Any service. One typed client." width="100%" />
+</p>
 
-<h1 align="center" style="margin-top:-25px">fastSDK</h1>
 <p align="center">
-  <img align="center" src="docs/fastsdk_logo.png" height="256" />
+  <a href="https://pypi.org/project/fastsdk/"><img src="https://img.shields.io/pypi/v/fastsdk?labelColor=000000&color=76B900" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/fastsdk/"><img src="https://img.shields.io/pypi/pyversions/fastsdk?labelColor=000000&color=76B900" alt="Python versions"></a>
+  <a href="https://github.com/SocAIty/fastSDK"><img src="https://img.shields.io/badge/github-SocAIty%2FfastSDK-76B900?labelColor=000000" alt="GitHub"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3-76B900?labelColor=000000" alt="License"></a>
 </p>
-<h3 align="center" style="margin-top:-10px">Built your SDK for any hosted service</h3>
+<h3 align="center" style="margin-top:-10px">Call any AI / web service like a native Python function</h3>
 
+fastSDK turns any hosted service — OpenAPI/FastAPI, [APIPod](https://github.com/SocAIty/APIPod), [RunPod](https://www.runpod.io), [Replicate](https://replicate.com), [Cog](https://github.com/replicate/cog) — into a Python client that feels like a local library: typed methods, file upload/download, async job handling and parallel execution included.
 
+Point it at a service. Call it like a function. That's the whole idea.
 
-Ever wanted to use web APIs as if they are any other python function?
-It was never easier to build an SDK for your hosted services, than it is with fastSDK.
-FastSDK creates a full functioning client for any openapi service.
+```python
+import fastsdk
 
-### Why?
+client = fastsdk.connect("http://localhost:8009")
+job = client.submit_job("/text2voice", text="hello world")
+audio = job.get_result()
+audio.save("hello.mp3")
+```
 
-Let's say you have created a webservice for example with [fastAPI](https://github.com/tiangolo/fastapi) or [flask](https://github.com/pallets/flask) and now you want to write a python client for it.
-In a first approach you would just use the [requests](https://pypi.org/project/requests/) library and send the requests to the server. However, while you do so,
-your cpu is idle waiting for the request to finish. Over time your requirements get bigger, suddenly you do not only have one endpoint but multiples.
-You will do different requests in parallel, you need to transfer files, and you struggle to do so in a structured, performant way. 
-Suddenly you end up in a threading, asyncio and complexity hell with many inconsistencies. You realize that you cannot transfer your 1GB video via an simple web request to your beautiful API.
-All these problems are solved with the fastSDK.
-Simple API calls, file uploads, job handling, and cloud storage providers are just a few features of the fastSDK.
+## Why fastSDK?
 
-FastSDK is designed to work beautifully with long-running services like machine learning and data processing endpoints.
-It works hand-in-hand with [APIPod](https://github.com/SocAIty/APIPod) that let's you build and deploy those services and endpoints easily.
+Calling a web service from Python sounds trivial until you actually do it in production:
+you wait synchronously on long-running ML jobs, you hand-write request code for every endpoint, you fight with file uploads (try sending a 1 GB video through `requests`), you poll job status loops, and you reinvent threading to run requests in parallel.
 
-### Service compatibility
+fastSDK solves exactly that, and nothing else:
+
+- **One call = one job.** Every call returns a job object immediately. Get the result when you need it, run hundreds of jobs in parallel meanwhile.
+- **Files just work.** Images, audio, video are handled by [media-toolkit](https://github.com/SocAIty/media-toolkit) — local paths, URLs, bytes or numpy arrays in; media objects out. Large files are uploaded via cloud storage (S3, Azure) when configured.
+- **Job-based providers are normalized.** Replicate, RunPod serverless, APIPod and Socaity all expose "submit, then poll" APIs with different wire formats. fastSDK handles submission, polling, progress and cancellation uniformly.
+- **Codegen when you want it, not when you don't.** Use `connect()` for instant access, or `generate_stub()` to get a typed `.py` client with one method per endpoint - autocomplete and docstrings included.
+
+## Installation
 
-Out of the box works with following services:
-- Services created with [APIPod](https://github.com/SocAIty/APIPod) which return a job object.
-- [Runpod](https://github.com/runpod/runpod-python) services
-- [Cog](https://github.com/replicate/cog) services
-- OpenAPI 3.0 / RestAPIs
-  - [fastAPI](https://github.com/tiangolo/fastapi)
-  - [Flask](https://flask.palletsprojects.com/en/2.0.x/)
-
-Can be used together with
-- [Socaity.ai](https://www.socaity.ai) services 
-- [Replicate.ai](https://www.replicate.com) services
-
-### Features:
-- Easy file upload, download thanks to [media-toolkit](https://github.com/SocAIty/media-toolkit). 
-  - Support for cloud storage providers like  [Azure Blob Storage](https://azure.microsoft.com/de-de/products/storage/blobs/?msockid=015b54a7ada76c452812402bac8c6dde) and [Amazon S3](https://aws.amazon.com/es/s3/).
-- Async and Threaded job support. Execute multiple requests and heavy preprocessing tasks in parallel and with high speed.
-  - Massively parallel job and request execution.
-- Working with services that create "Jobs". The SDK will wait for the job to finish and return the result.
-  - Support for [APIPod](https://github.com/SocAIty/APIPod) and [runpod (serverless)](https://www.runpod.io/serverless-gpu) endpoints.
-  - Retrieving the job status, progres and print status updates.
-- Streaming of files 
-- Automatic serialization of data types
-
-# Installation
-
-To install from PyPI:
-This version includes all features needed to conveniently wrap your API into an SDK.
 ```bash
-pip install fastsdk
+pip install fastsdk           # core
+pip install fastsdk[replicate]  # + Replicate model support
+```
+
+## Get started
+
+### Option A: connect — use a service right now
+
+No files, no codegen. Works with a URL, an `openapi.json` path, or a Replicate model reference.
+
+```python
+import fastsdk
+
+client = fastsdk.connect("http://localhost:8009")
+job = client.submit_job("/text2voice", text="hello world")
+result = job.get_result()
 ```
 
-# Get started
+### Option B: generate_stub — typed clients for real projects
 
-First get your openapi.json file from your service usually under:  [http://localhost:8000/openapi.json](http://localhost:8000/openapi.json).
-You can use an example openapi.json from our face2face service located in this repos under [/test/test_files/face2face.json](/test/test_files/face2face.json)
+Generates a `.py` file with one typed method per endpoint. This is your SDK.
 
 ```python
-# create a full working client stub 
-create_sdk("openapi.json", save_path="my_service.py")
+import fastsdk
+
+stub = fastsdk.generate_stub("http://localhost:8009", save_path="clients/")
+print(stub.path, stub.class_name)
 
-# Import the client. It will have a method for each of your service endpoints including all parameters and its default values.
-from my_service import awesome_client
-mySDK = awesome_client()
-mySDK.my_method(...)
+# use it immediately ...
+client = stub.client()
+job = client.text2voice(text="hello world")
+
+# ... or import it in your next run like any other module
+# from clients.speechcraft import speechcraft
+# client = speechcraft()
 ```
 
-### Authorization
-Let's say you have created your SDK (client) with ```@fastSDK``` and named it face2face
-Then you can init it with arguments. In this moment you can pass the api key.
+Re-running `generate_stub` is safe: the file is overwritten and the service registration is updated, not duplicated.
+
+### Replicate models
+
+Official models (called via `/v1/models/{owner}/{name}/predictions`) and community models (called via `/v1/predictions` with a version) are resolved automatically — you just name the model:
+
 ```python
-f2f = face2face(api_key="my_api_key")
-api_job = f2f.swap_img_to_img(source_img="my_face_1.jpg", target_img="my_face_2.jpg")
-swapped_img = api_job.get_result()
+import fastsdk  # requires: pip install fastsdk[replicate] and REPLICATE_API_KEY
+
+stub = fastsdk.generate_stub("replicate:black-forest-labs/flux-schnell", save_path="clients/")
+flux = stub.client()
+job = flux(prompt="a t-rex on a skateboard")
+image = job.get_result()
 ```
-Alternatively you can set the api_keys in the settings and give them names like "runpod".
-Add this at the beginning of your script.
+
+### Working with jobs
 
 ```python
-import os
-import settings
-settings.api_keys["runpod"] = os.getenv("my_api_key")
-``` 
+job = client.swap_img_to_img(source_img="face1.jpg", target_img="face2.jpg")
+job.get_result()          # block until done and return the result
+job.cancel()              # cancel locally and remotely (provider permitting)
+
+# run many jobs in parallel - this is where fastSDK shines
+jobs = [client.text2voice(text=t) for t in hundred_texts]
+results = fastsdk.gather_results(jobs)
+```
+
+### API keys
+
+Pass `api_key=...` to `connect()`, `generate_stub()` or the client constructor — or set environment variables: `REPLICATE_API_KEY`, `RUNPOD_API_KEY`, `SOCAITY_API_KEY`, or `<SERVICE_ID>_API_KEY` for your own services.
+
+## The four concepts
+
+| Concept | What it is |
+|---|---|
+| **Service definition** | The parsed, normalized description of a service: endpoints, parameters, address, provider type. Get one with `fastsdk.inspect_service(source)` — it has no side effects. |
+| **Registry** | An in-process directory of service definitions, shared by all clients. `register_service()` adds to it; generated stubs look their service up in it by ID. |
+| **Client** | The runtime object you call (`FastClient`). It submits jobs to the service. `connect()` gives you a generic one instantly. |
+| **Stub** | A generated `.py` file containing a client subclass with one typed method per endpoint. Made by `generate_stub()`; it's plain code — read it, version it, ship it. |
+
+## CLI
+
+Everything above also works from the terminal — same verbs, same behavior:
+
+```bash
+# What can this service do?
+fastsdk inspect http://localhost:8009
+
+# Generate a typed client stub
+fastsdk generate http://localhost:8009 -o clients/ --name SpeechCraft
+fastsdk generate replicate:black-forest-labs/flux-schnell --api-key r8_...
+
+# Call an endpoint without writing any code (curl for AI services)
+fastsdk call http://localhost:8009 /text2voice --text "hello world" -o hello.mp3
+
+# Keep services around by name (persisted in ~/.fastsdk/registry)
+fastsdk registry add http://localhost:8009 --name speechcraft
+fastsdk registry list
+fastsdk call speechcraft /text2voice --text "hi again"
+```
 
-API keys can be set in environment variables, when creating the Service Client or when initializing your SDK.
-In settings.py the default environment variables are set.
+## Service compatibility
 
-# FastSDK :two_hearts: APIPod
+Works out of the box with:
+- [APIPod](https://github.com/SocAIty/APIPod) services (job-based, the natural counterpart to fastSDK)
+- [Replicate](https://replicate.com) models (official and community)
+- [RunPod serverless](https://www.runpod.io/serverless-gpu) endpoints
+- [Cog](https://github.com/replicate/cog) services
+- Any OpenAPI 3.0 service ([FastAPI](https://github.com/tiangolo/fastapi), [Flask](https://flask.palletsprojects.com/), ...)
+- [Socaity.ai](https://www.socaity.ai) services
+
+## fastSDK + APIPod
 
 <img src="https://github.com/SocAIty/APIPod/blob/main/docs/fastsdk_to_apipod.png?raw=true" width="50%" />
 
-[APIPod](https://github.com/SocAIty/APIPod) allows you to easily create and deploy services that can be used with fastSDK.
-They are two beating hearts :two_hearts: beating in harmony for client <--> service interaction.
-Create your service now.
+[APIPod](https://github.com/SocAIty/APIPod) builds and deploys the services; fastSDK consumes them. Two beating hearts :two_hearts: for service ↔ client interaction.
+
 
-# Contribute
+## Contribute
 
-We at socaity want to provide the best tools to bring generative AI to the cloud.
-Please report bugs, your ideas and feature requests in the issues section.
-fastSDK is licensed under the MIT license and free-to-use.
+We at SocAIty want to provide the best tools to bring generative AI to the cloud.
+Report bugs, ideas and feature requests in the issues section.
+fastSDK is MIT-licensed and free to use. Leave a star to support us!
 
-## Note: THE PACKAGE IS STILL IN DEVELOPMENT!
-#### LEAVE A STAR TO SUPPORT US. ANY BUG REPORT OR CONTRIBUTION IS HIGHLY APPRECIATED.
+---
+<p align="center">
+  Made with ❤️ by <a href="https://www.socaity.ai?utm_source=github&utm_content=fastsdk-20-29-06-2026">SocAIty</a>
+</p>

fastsdk-0.3.1/README.md

@@ -0,0 +1,165 @@
+<p align="center">
+  <img src="docs/assets/banner.png" alt="fastSDK. Any service. One typed client." width="100%" />
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/fastsdk/"><img src="https://img.shields.io/pypi/v/fastsdk?labelColor=000000&color=76B900" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/fastsdk/"><img src="https://img.shields.io/pypi/pyversions/fastsdk?labelColor=000000&color=76B900" alt="Python versions"></a>
+  <a href="https://github.com/SocAIty/fastSDK"><img src="https://img.shields.io/badge/github-SocAIty%2FfastSDK-76B900?labelColor=000000" alt="GitHub"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-GPLv3-76B900?labelColor=000000" alt="License"></a>
+</p>
+<h3 align="center" style="margin-top:-10px">Call any AI / web service like a native Python function</h3>
+
+fastSDK turns any hosted service — OpenAPI/FastAPI, [APIPod](https://github.com/SocAIty/APIPod), [RunPod](https://www.runpod.io), [Replicate](https://replicate.com), [Cog](https://github.com/replicate/cog) — into a Python client that feels like a local library: typed methods, file upload/download, async job handling and parallel execution included.
+
+Point it at a service. Call it like a function. That's the whole idea.
+
+```python
+import fastsdk
+
+client = fastsdk.connect("http://localhost:8009")
+job = client.submit_job("/text2voice", text="hello world")
+audio = job.get_result()
+audio.save("hello.mp3")
+```
+
+## Why fastSDK?
+
+Calling a web service from Python sounds trivial until you actually do it in production:
+you wait synchronously on long-running ML jobs, you hand-write request code for every endpoint, you fight with file uploads (try sending a 1 GB video through `requests`), you poll job status loops, and you reinvent threading to run requests in parallel.
+
+fastSDK solves exactly that, and nothing else:
+
+- **One call = one job.** Every call returns a job object immediately. Get the result when you need it, run hundreds of jobs in parallel meanwhile.
+- **Files just work.** Images, audio, video are handled by [media-toolkit](https://github.com/SocAIty/media-toolkit) — local paths, URLs, bytes or numpy arrays in; media objects out. Large files are uploaded via cloud storage (S3, Azure) when configured.
+- **Job-based providers are normalized.** Replicate, RunPod serverless, APIPod and Socaity all expose "submit, then poll" APIs with different wire formats. fastSDK handles submission, polling, progress and cancellation uniformly.
+- **Codegen when you want it, not when you don't.** Use `connect()` for instant access, or `generate_stub()` to get a typed `.py` client with one method per endpoint - autocomplete and docstrings included.
+
+## Installation
+
+```bash
+pip install fastsdk           # core
+pip install fastsdk[replicate]  # + Replicate model support
+```
+
+## Get started
+
+### Option A: connect — use a service right now
+
+No files, no codegen. Works with a URL, an `openapi.json` path, or a Replicate model reference.
+
+```python
+import fastsdk
+
+client = fastsdk.connect("http://localhost:8009")
+job = client.submit_job("/text2voice", text="hello world")
+result = job.get_result()
+```
+
+### Option B: generate_stub — typed clients for real projects
+
+Generates a `.py` file with one typed method per endpoint. This is your SDK.
+
+```python
+import fastsdk
+
+stub = fastsdk.generate_stub("http://localhost:8009", save_path="clients/")
+print(stub.path, stub.class_name)
+
+# use it immediately ...
+client = stub.client()
+job = client.text2voice(text="hello world")
+
+# ... or import it in your next run like any other module
+# from clients.speechcraft import speechcraft
+# client = speechcraft()
+```
+
+Re-running `generate_stub` is safe: the file is overwritten and the service registration is updated, not duplicated.
+
+### Replicate models
+
+Official models (called via `/v1/models/{owner}/{name}/predictions`) and community models (called via `/v1/predictions` with a version) are resolved automatically — you just name the model:
+
+```python
+import fastsdk  # requires: pip install fastsdk[replicate] and REPLICATE_API_KEY
+
+stub = fastsdk.generate_stub("replicate:black-forest-labs/flux-schnell", save_path="clients/")
+flux = stub.client()
+job = flux(prompt="a t-rex on a skateboard")
+image = job.get_result()
+```
+
+### Working with jobs
+
+```python
+job = client.swap_img_to_img(source_img="face1.jpg", target_img="face2.jpg")
+job.get_result()          # block until done and return the result
+job.cancel()              # cancel locally and remotely (provider permitting)
+
+# run many jobs in parallel - this is where fastSDK shines
+jobs = [client.text2voice(text=t) for t in hundred_texts]
+results = fastsdk.gather_results(jobs)
+```
+
+### API keys
+
+Pass `api_key=...` to `connect()`, `generate_stub()` or the client constructor — or set environment variables: `REPLICATE_API_KEY`, `RUNPOD_API_KEY`, `SOCAITY_API_KEY`, or `<SERVICE_ID>_API_KEY` for your own services.
+
+## The four concepts
+
+| Concept | What it is |
+|---|---|
+| **Service definition** | The parsed, normalized description of a service: endpoints, parameters, address, provider type. Get one with `fastsdk.inspect_service(source)` — it has no side effects. |
+| **Registry** | An in-process directory of service definitions, shared by all clients. `register_service()` adds to it; generated stubs look their service up in it by ID. |
+| **Client** | The runtime object you call (`FastClient`). It submits jobs to the service. `connect()` gives you a generic one instantly. |
+| **Stub** | A generated `.py` file containing a client subclass with one typed method per endpoint. Made by `generate_stub()`; it's plain code — read it, version it, ship it. |
+
+## CLI
+
+Everything above also works from the terminal — same verbs, same behavior:
+
+```bash
+# What can this service do?
+fastsdk inspect http://localhost:8009
+
+# Generate a typed client stub
+fastsdk generate http://localhost:8009 -o clients/ --name SpeechCraft
+fastsdk generate replicate:black-forest-labs/flux-schnell --api-key r8_...
+
+# Call an endpoint without writing any code (curl for AI services)
+fastsdk call http://localhost:8009 /text2voice --text "hello world" -o hello.mp3
+
+# Keep services around by name (persisted in ~/.fastsdk/registry)
+fastsdk registry add http://localhost:8009 --name speechcraft
+fastsdk registry list
+fastsdk call speechcraft /text2voice --text "hi again"
+```
+
+## Service compatibility
+
+Works out of the box with:
+- [APIPod](https://github.com/SocAIty/APIPod) services (job-based, the natural counterpart to fastSDK)
+- [Replicate](https://replicate.com) models (official and community)
+- [RunPod serverless](https://www.runpod.io/serverless-gpu) endpoints
+- [Cog](https://github.com/replicate/cog) services
+- Any OpenAPI 3.0 service ([FastAPI](https://github.com/tiangolo/fastapi), [Flask](https://flask.palletsprojects.com/), ...)
+- [Socaity.ai](https://www.socaity.ai) services
+
+## fastSDK + APIPod
+
+<img src="https://github.com/SocAIty/APIPod/blob/main/docs/fastsdk_to_apipod.png?raw=true" width="50%" />
+
+[APIPod](https://github.com/SocAIty/APIPod) builds and deploys the services; fastSDK consumes them. Two beating hearts :two_hearts: for service ↔ client interaction.
+
+
+## Contribute
+
+We at SocAIty want to provide the best tools to bring generative AI to the cloud.
+Report bugs, ideas and feature requests in the issues section.
+fastSDK is MIT-licensed and free to use. Leave a star to support us!
+
+---
+<p align="center">
+  Made with ❤️ by <a href="https://www.socaity.ai?utm_source=github&utm_content=fastsdk-20-29-06-2026">SocAIty</a>
+</p>

fastsdk-0.3.1/fastsdk/__init__.py

@@ -0,0 +1,27 @@
+from .fastStub import FastStub
+from media_toolkit import MediaFile, ImageFile, VideoFile, AudioFile
+from meseex import gather_results, gather_results_async
+
+from .api import (
+    connect,
+    inspect_service,
+    generate_stub,
+    register_service,
+    get_service,
+    list_services,
+    remove_service,
+)  # create_sdk is a deprecated alias of generate_stub
+from .service_interaction.api_seex import APISeex
+from .fastClient import FastClient
+from .fastSDK import FastSDK
+
+
+__all__ = [
+    # primary API
+    'connect', 'inspect_service', 'generate_stub', 'register_service',
+    'get_service', 'list_services', 'remove_service',
+    # classes
+    'FastStub', 'FastClient', 'APISeex', 'FastSDK',
+    # re-exports
+    'MediaFile', 'ImageFile', 'VideoFile', 'AudioFile', 'gather_results', 'gather_results_async'
+]

fastsdk-0.3.1/fastsdk/api.py

@@ -0,0 +1,132 @@
+"""
+The public, module-level API of fastsdk.
+
+These functions wrap the FastSDK singleton so users never have to deal with it directly:
+
+    import fastsdk
+
+    client = fastsdk.connect("http://localhost:8009")          # use a service right now
+    stub = fastsdk.generate_stub("http://localhost:8009")      # generate a client stub file
+    sd = fastsdk.inspect_service("replicate:owner/name")       # look at a service without side effects
+    sd = fastsdk.register_service("./openapi.json")            # add a service to the registry
+"""
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Union, TYPE_CHECKING
+
+from socaity_schemas.service_definitions import ServiceDefinition
+
+from fastsdk.fastSDK import FastSDK
+
+if TYPE_CHECKING:
+    from fastsdk.fastClient import FastClient
+    from fastsdk.fastStub import FastStub
+
+
+def connect(
+    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    api_key: Optional[str] = None,
+    **kwargs
+) -> 'FastClient':
+    """
+    Connect to a service and get a ready-to-use client - no code generation, no files.
+
+    Args:
+        source: Service URL ("http://localhost:8009"), openapi.json path/dict, ServiceDefinition,
+            Replicate model reference ("replicate:owner/name") or a registered service ID/name.
+        api_key: Optional API key. Falls back to environment variables.
+        **kwargs: Additional service loading arguments (see inspect_service).
+
+    Returns:
+        FastClient. Call endpoints generically via client.submit_job("/endpoint", **params).
+
+    Example:
+        client = fastsdk.connect("http://localhost:8009")
+        job = client.submit_job("/text2voice", text="hello world")
+        audio = job.get_result()
+    """
+    return FastSDK().connect(source, api_key=api_key, **kwargs)
+
+
+def inspect_service(
+    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    api_key: Optional[str] = None,
+    **kwargs
+) -> ServiceDefinition:
+    """
+    Load and parse a service into a ServiceDefinition without registering it anywhere.
+    Pure function: no side effects on the registry.
+
+    Args:
+        source: Service URL, openapi.json path/dict, Replicate model reference or ServiceDefinition.
+        api_key: Required for RunPod and Replicate sources.
+        **kwargs: Overrides such as service_name, service_id, service_address, specification, ...
+
+    Returns:
+        ServiceDefinition with endpoints, parameters and the resolved service address.
+    """
+    return FastSDK.inspect_service(source, api_key=api_key, **kwargs)
+
+
+def generate_stub(
+    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    save_path: Optional[str] = None,
+    class_name: Optional[str] = None,
+    template: Optional[str] = None,
+    **kwargs
+) -> 'FastStub':
+    """
+    Generate a Python client stub file (.py) for a service. The generated class has one typed
+    method per endpoint. The service is also registered in the registry, so the stub can be
+    used immediately in the same process.
+
+    Args:
+        source: Service URL, openapi.json path/dict, ServiceDefinition, Replicate model
+            reference or a registered service ID/name.
+        save_path: File or directory path for the generated .py file. Defaults to the current directory.
+        class_name: Name of the generated class. Defaults to the (normalized) service name.
+        template: Optional custom Jinja2 template path.
+        **kwargs: Additional service loading arguments (e.g. api_key, service_name).
+
+    Returns:
+        GeneratedStub with .path, .class_name, .service_definition and .client().
+
+    Example:
+        stub = fastsdk.generate_stub("http://localhost:8009", save_path="clients/")
+        client = stub.client()                     # use it right away
+        # or in the next run:
+        # from clients.speechcraft import SpeechCraft
+    """
+    return FastSDK().generate_stub(source, save_path=save_path, class_name=class_name, template=template, **kwargs)
+
+
+def register_service(
+    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    **kwargs
+) -> ServiceDefinition:
+    """
+    Load a service and add it to the registry. Idempotent: re-registering a service with the
+    same ID replaces the previous entry.
+
+    Args:
+        source: Service URL, openapi.json path/dict, Replicate model reference or ServiceDefinition.
+        **kwargs: Overrides such as service_name, service_id, service_address, api_key, ...
+
+    Returns:
+        The registered ServiceDefinition.
+    """
+    return FastSDK().register_service(source, **kwargs)
+
+
+def get_service(service_id_or_name: str) -> Optional[ServiceDefinition]:
+    """Get a registered service by ID or name. Returns None if not found."""
+    return FastSDK().get_service(service_id_or_name)
+
+
+def list_services() -> List[ServiceDefinition]:
+    """List all services currently in the registry."""
+    return FastSDK().service_registry.list_services()
+
+
+def remove_service(service_id_or_name: str) -> bool:
+    """Remove a service from the registry. Returns True if it was removed."""
+    return FastSDK().service_registry.remove_service(service_id_or_name)