fastsdk 0.3.1__tar.gz → 0.4.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fastsdk
-Version: 0.3.1
+Version: 0.4.2
 Summary: Turn any AI/web service (OpenAPI, Replicate, RunPod, APIPod) into a native-feeling Python client.
 Author: SocAIty
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -691,8 +691,8 @@ Requires-Dist: media-toolkit>=00.02.22
 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
+Requires-Dist: apipod-registry>=0.1.1
+Requires-Dist: socaity-schemas>=0.1.1
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
 Provides-Extra: replicate
@@ -811,8 +811,8 @@ Pass `api_key=...` to `connect()`, `generate_stub()` or the client constructor
 
 | 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. |
+| **Service** | An `AIService` (from socaity-schemas) with one deployment: hosting provider, address, and the parsed `ServiceContract` (endpoints, parameters, whether responses are polled jobs). Get one with `fastsdk.inspect_service(source)`, it has no side effects. |
+| **Registry** | An in-process directory of services, 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. |
 

{fastsdk-0.3.1 → fastsdk-0.4.2}/README.md

@@ -110,8 +110,8 @@ Pass `api_key=...` to `connect()`, `generate_stub()` or the client constructor
 
 | 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. |
+| **Service** | An `AIService` (from socaity-schemas) with one deployment: hosting provider, address, and the parsed `ServiceContract` (endpoints, parameters, whether responses are polled jobs). Get one with `fastsdk.inspect_service(source)`, it has no side effects. |
+| **Registry** | An in-process directory of services, 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. |
 

{fastsdk-0.3.1 → fastsdk-0.4.2}/fastsdk/__init__.py

@@ -10,7 +10,7 @@ from .api import (
     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

{fastsdk-0.3.1 → fastsdk-0.4.2}/fastsdk/api.py

@@ -7,13 +7,13 @@ These functions wrap the FastSDK singleton so users never have to deal with it d
 
     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
+    service = fastsdk.inspect_service("replicate:owner/name")  # look at a service without side effects
+    service = 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 socaity_schemas.platform import AIService
 
 from fastsdk.fastSDK import FastSDK
 
@@ -23,7 +23,7 @@ if TYPE_CHECKING:
 
 
 def connect(
-    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    source: Union[str, Path, Dict[str, Any], AIService],
     api_key: Optional[str] = None,
     **kwargs
 ) -> 'FastClient':
@@ -31,7 +31,7 @@ def connect(
     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,
+        source: Service URL ("http://localhost:8009"), openapi.json path/dict, AIService,
             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).
@@ -48,27 +48,28 @@ def connect(
 
 
 def inspect_service(
-    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    source: Union[str, Path, Dict[str, Any], AIService],
     api_key: Optional[str] = None,
     **kwargs
-) -> ServiceDefinition:
+) -> AIService:
     """
-    Load and parse a service into a ServiceDefinition without registering it anywhere.
+    Load and parse a service into an AIService 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.
+        source: Service URL, openapi.json path/dict, Replicate model reference or AIService.
         api_key: Required for RunPod and Replicate sources.
-        **kwargs: Overrides such as service_name, service_id, service_address, specification, ...
+        **kwargs: Overrides such as provider, service_id, name.
 
     Returns:
-        ServiceDefinition with endpoints, parameters and the resolved service address.
+        AIService whose primary deployment carries the parsed ServiceContract
+        (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],
+    source: Union[str, Path, Dict[str, Any], AIService],
     save_path: Optional[str] = None,
     class_name: Optional[str] = None,
     template: Optional[str] = None,
@@ -80,7 +81,7 @@ def generate_stub(
     used immediately in the same process.
 
     Args:
-        source: Service URL, openapi.json path/dict, ServiceDefinition, Replicate model
+        source: Service URL, openapi.json path/dict, AIService, 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.
@@ -88,7 +89,7 @@ def generate_stub(
         **kwargs: Additional service loading arguments (e.g. api_key, service_name).
 
     Returns:
-        GeneratedStub with .path, .class_name, .service_definition and .client().
+        FastStub with .path, .class_name, .service and .client().
 
     Example:
         stub = fastsdk.generate_stub("http://localhost:8009", save_path="clients/")
@@ -100,29 +101,29 @@ def generate_stub(
 
 
 def register_service(
-    source: Union[str, Path, Dict[str, Any], ServiceDefinition],
+    source: Union[str, Path, Dict[str, Any], AIService],
     **kwargs
-) -> ServiceDefinition:
+) -> AIService:
     """
     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, ...
+        source: Service URL, openapi.json path/dict, Replicate model reference or AIService.
+        **kwargs: Overrides such as service_name, service_id, service_address, provider, api_key, ...
 
     Returns:
-        The registered ServiceDefinition.
+        The registered AIService.
     """
     return FastSDK().register_service(source, **kwargs)
 
 
-def get_service(service_id_or_name: str) -> Optional[ServiceDefinition]:
+def get_service(service_id_or_name: str) -> Optional[AIService]:
     """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]:
+def list_services() -> List[AIService]:
     """List all services currently in the registry."""
     return FastSDK().service_registry.list_services()
 

{fastsdk-0.3.1 → fastsdk-0.4.2}/fastsdk/cli.py

@@ -18,9 +18,11 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, List, Optional, Union
 
-from apipod_registry import Registry
-from socaity_schemas.service_definitions import ServiceDefinition
-from apipod_registry.service_registry.file_system_registry import FileSystemStore
+from apipod_registry import FileSystemStore, Registry
+from socaity_schemas.contract.address import service_url
+from socaity_schemas.platform import AIService
+
+from fastsdk.service_access import service_address, service_contract, service_provider
 
 
 DEFAULT_REGISTRY_PATH = Path.home() / ".fastsdk" / "registry"
@@ -38,8 +40,8 @@ def _open_persistent_registry() -> Registry:
     return Registry(service_store=FileSystemStore(path=str(_registry_path())))
 
 
-def _resolve_source(source: str) -> Union[str, ServiceDefinition]:
-    """If the source matches a service in the persistent CLI registry, use that definition."""
+def _resolve_source(source: str) -> Union[str, AIService]:
+    """If the source matches a service in the persistent CLI registry, use that service."""
     try:
         stored = _open_persistent_registry().get_service(source)
     except Exception:
@@ -47,27 +49,37 @@ def _resolve_source(source: str) -> Union[str, ServiceDefinition]:
     return stored or source
 
 
-def _service_summary(sd: ServiceDefinition) -> str:
-    address = getattr(sd.service_address, "url", None) or "-"
-    return f"{sd.display_name} (id: {sd.id}, spec: {sd.specification or 'openapi'}, address: {address})"
+def _address_url(service: AIService) -> str:
+    address = service_address(service)
+    return service_url(address) if address else "-"
+
+
+def _service_summary(service: AIService) -> str:
+    contract = service_contract(service)
+    return (
+        f"{service.display_name} (id: {service.id}, spec: {contract.specification}, "
+        f"provider: {service_provider(service)}, address: {_address_url(service)})"
+    )
 
 
-def _print_service(sd: ServiceDefinition, as_json: bool = False):
+def _print_service(service: AIService, as_json: bool = False):
     if as_json:
-        print(json.dumps(sd.model_dump(exclude_none=True), indent=2, default=str))
+        print(json.dumps(service.model_dump(exclude_none=True), indent=2, default=str))
         return
 
     from fastsdk.sdk_factory.sdk_factory import _get_type_hint
 
-    print(f"Service:  {sd.display_name}")
-    print(f"ID:       {sd.id}")
-    print(f"Spec:     {sd.specification or 'openapi'}")
-    print(f"Address:  {getattr(sd.service_address, 'url', None) or '-'}")
-    if sd.description:
-        desc = sd.description.strip().split("\n")[0]
+    contract = service_contract(service)
+    print(f"Service:  {service.display_name}")
+    print(f"ID:       {service.id}")
+    print(f"Spec:     {contract.specification}")
+    print(f"Provider: {service_provider(service)}")
+    print(f"Address:  {_address_url(service)}")
+    if service.description:
+        desc = service.description.strip().split("\n")[0]
         print(f"About:    {desc[:120]}")
     print("Endpoints:")
-    for endpoint in sd.endpoints:
+    for endpoint in contract.endpoints:
         print(f"  {endpoint.path}")
         for param in endpoint.parameters:
             if param.location not in ("body", "query"):
@@ -150,8 +162,8 @@ def _import_hint(stub_path: str, class_name: str) -> str:
 
 def cmd_inspect(args: argparse.Namespace):
     import fastsdk
-    sd = fastsdk.inspect_service(_resolve_source(args.source), api_key=args.api_key)
-    _print_service(sd, as_json=args.json)
+    service = fastsdk.inspect_service(_resolve_source(args.source), api_key=args.api_key)
+    _print_service(service, as_json=args.json)
 
 
 def cmd_generate(args: argparse.Namespace):
@@ -167,10 +179,9 @@ def cmd_generate(args: argparse.Namespace):
         api_key=args.api_key,
         **kwargs
     )
-    sd = stub.service_definition
     print(f"Generated {stub.path}")
     print(f"  class:   {stub.class_name}")
-    print(f"  service: {_service_summary(sd)}")
+    print(f"  service: {_service_summary(stub.service)}")
     print()
     print("Use it:")
     print(f"  {_import_hint(stub.path, stub.class_name)}")
@@ -182,17 +193,18 @@ def cmd_call(args: argparse.Namespace, extra: List[str]):
 
     params = _parse_endpoint_params(extra)
     client = FastClient(_resolve_source(args.source), api_key=args.api_key)
-    sd = client.service_definition
+    service = client.service
+    endpoints = service_contract(service).endpoints
 
     endpoint = args.endpoint
     if not endpoint:
-        if len(sd.endpoints) == 1:
-            endpoint = sd.endpoints[0].path
+        if len(endpoints) == 1:
+            endpoint = endpoints[0].path
         else:
-            paths = "\n  ".join(ep.path for ep in sd.endpoints)
+            paths = "\n  ".join(ep.path for ep in endpoints)
             raise SystemExit(f"Service has multiple endpoints, please specify one:\n  {paths}")
 
-    print(f"Calling {endpoint} on {sd.display_name} ...")
+    print(f"Calling {endpoint} on {service.display_name} ...")
     try:
         job = client.submit_job(endpoint, **params)
         result = job.wait_for_result()
@@ -216,20 +228,18 @@ def cmd_registry(args: argparse.Namespace):
         if not services:
             print(f"No services registered ({_registry_path()}).")
             return
-        for sd in services:
-            print(f"  {_service_summary(sd)}")
+        for service in services:
+            print(f"  {_service_summary(service)}")
 
     elif args.registry_command == "add":
-        sd = fastsdk.inspect_service(
+        service = fastsdk.inspect_service(
             args.source,
             service_id=args.id,
-            service_name=args.name,
+            name=args.name,
             api_key=args.api_key
         )
-        if sd.id and registry.get_service(sd.id):
-            registry.remove_service(sd.id)
-        registry.register_service(sd)
-        print(f"Registered {_service_summary(sd)}")
+        registry.add_service(service)
+        print(f"Registered {_service_summary(service)}")
         print(f"Registry: {_registry_path()}")
 
     elif args.registry_command == "remove":
@@ -239,10 +249,10 @@ def cmd_registry(args: argparse.Namespace):
             raise SystemExit(f"Service '{args.id}' not found in registry ({_registry_path()}).")
 
     elif args.registry_command == "show":
-        sd = registry.get_service(args.id)
-        if not sd:
+        service = registry.get_service(args.id)
+        if not service:
             raise SystemExit(f"Service '{args.id}' not found in registry ({_registry_path()}).")
-        _print_service(sd, as_json=args.json)
+        _print_service(service, as_json=args.json)
 
     else:
         raise SystemExit("Usage: fastsdk registry {list,add,remove,show}")

{fastsdk-0.3.1 → fastsdk-0.4.2}/fastsdk/fastClient.py

@@ -2,13 +2,22 @@ from pathlib import Path
 from typing import Any, Dict, Optional, Union, TYPE_CHECKING
 import os
 
-from socaity_schemas.service_definitions import ServiceDefinition, ReplicateServiceAddress, RunpodServiceAddress, SocaityServiceAddress
+from socaity_schemas.platform import AIService, PriceEstimate
+
 from fastsdk.fastSDK import FastSDK
+from fastsdk.service_access import service_provider
 
 if TYPE_CHECKING:
     from fastsdk.service_interaction.api_seex import APISeex
 
 
+_PROVIDER_API_KEY_ENV = {
+    "socaity": "SOCAITY_API_KEY",
+    "runpod": "RUNPOD_API_KEY",
+    "replicate": "REPLICATE_API_KEY",
+}
+
+
 class FastClient:
     """
     The runtime client for a service. Generated stubs inherit from this class, but it can also be
@@ -16,7 +25,7 @@ class FastClient:
 
     A FastClient can be created from:
     - a registered service ID or name (this is what generated stubs do)
-    - a service URL, an openapi.json file path, a spec dict or a ServiceDefinition
+    - a service URL, an openapi.json file path, a spec dict or an AIService
     - a Replicate model reference like "replicate:owner/name"
 
     If the source is not yet in the registry, it is loaded and registered automatically.
@@ -27,7 +36,7 @@ class FastClient:
     """
     def __init__(
         self,
-        service: Union[str, Path, Dict[str, Any], ServiceDefinition, None] = None,
+        service: Union[str, Path, Dict[str, Any], AIService, None] = None,
         api_key: Optional[str] = None,
         temporary: bool = False,
         service_name_or_id: Optional[str] = None,
@@ -36,7 +45,7 @@ class FastClient:
         """
         Args:
             service: Service source. A registered service ID/name, a URL, a spec file path,
-                a spec dict, a ServiceDefinition or a Replicate model reference.
+                a spec dict, an AIService or a Replicate model reference.
             api_key: Optional API key for the service. If not provided, it is looked up in
                 the environment variables (e.g. REPLICATE_API_KEY, RUNPOD_API_KEY, <SERVICE_ID>_API_KEY).
             temporary: If True, the service is removed from the registry when the client is deleted.
@@ -48,25 +57,23 @@ class FastClient:
         self.temporary = temporary
 
         if service is None and service_name_or_id is None:
-            raise ValueError("Provide a service source (URL, file, dict, ServiceDefinition) or a registered service ID/name.")
+            raise ValueError("Provide a service source (URL, file, dict, AIService) or a registered service ID/name.")
 
         if service_name_or_id is not None:
-            # Strict lookup path used by generated stubs.
-            self.service_definition = self.fsdk.service_registry.get_service(service_name_or_id)
-            if not self.service_definition:
+            self.service = self.fsdk.service_registry.get_service(service_name_or_id)
+            if not self.service:
                 raise ValueError(
                     f"Service '{service_name_or_id}' not found in the registry. "
                     f"Register it first with fastsdk.register_service(...) or regenerate the stub with fastsdk.generate_stub(...)."
                 )
         else:
-            self.service_definition = self._resolve_service(service, api_key, **load_kwargs)
+            self.service = self._resolve_service(service, api_key, **load_kwargs)
 
         # try to get api key from global settings if not provided
         self.api_key = api_key or self._get_api_key()
-        # Load the provider stack (client, file handler, parser) for this service.
-        self.fsdk.provider_stacks.load(self.service_definition.id, self.api_key)
+        self.fsdk.provider_stacks.load(self.service.id, self.api_key)
 
-    def _resolve_service(self, service, api_key: Optional[str], **load_kwargs) -> ServiceDefinition:
+    def _resolve_service(self, service, api_key: Optional[str], **load_kwargs) -> AIService:
         # A plain string might be a registered service ID/name - check the registry first.
         if isinstance(service, str):
             registered = self.fsdk.service_registry.get_service(service)
@@ -75,31 +82,37 @@ class FastClient:
         # Otherwise treat it as a spec source: load and register it.
         # Temporary clients always get their own registry entry (update_existing=False),
         # so removing it on cleanup never deletes a permanently registered service.
-        service_def = self.fsdk.register_service(service, api_key=api_key, update_existing=not self.temporary, **load_kwargs)
-        return service_def
+        return self.fsdk.register_service(service, api_key=api_key, update_existing=not self.temporary, **load_kwargs)
 
     def _get_api_key(self):
-        # for global services
-        if isinstance(self.service_definition.service_address, SocaityServiceAddress):
-            return os.getenv("SOCAITY_API_KEY", None)
-        elif isinstance(self.service_definition.service_address, RunpodServiceAddress):
-            return os.getenv("RUNPOD_API_KEY", None)
-        elif isinstance(self.service_definition.service_address, ReplicateServiceAddress):
-            return os.getenv("REPLICATE_API_KEY", None)
-            
-        # for locals try by service_id
-        return os.getenv(self.service_definition.id.upper() + "_API_KEY", None)
+        env_var = _PROVIDER_API_KEY_ENV.get(service_provider(self.service))
+        if env_var:
+            return os.getenv(env_var, None)
+        return os.getenv(self.service.id.upper() + "_API_KEY", None)
 
     def submit_job(self, endpoint_id: str, **kwargs) -> 'APISeex':
-        return self.fsdk.api_job_manager.submit_job(self.service_definition.id, endpoint_id, data=kwargs)
+        return self.fsdk.api_job_manager.submit_job(self.service.id, endpoint_id, data=kwargs)
+
+    def estimate(self, endpoint_path: str, **params) -> PriceEstimate:
+        """Estimate price and runtime. Implemented by the Socaity provider API client.
+
+        Requires ``socaity-cli`` when the provider is Socaity (signaled via ``@requires``).
+        """
+        stack = self.fsdk.provider_stacks.require(self.service.id)
+        estimate_fn = getattr(stack.api_client, "estimate", None)
+        if estimate_fn is None:
+            raise NotImplementedError(
+                "estimate() is only available for Socaity-hosted services "
+                f"(provider client: {type(stack.api_client).__name__})"
+            )
+        return estimate_fn(endpoint_path, **params)
 
     def close(self):
         """Remove the service from the registry if this client registered it temporarily."""
-        if self.temporary and getattr(self, 'service_definition', None) and hasattr(self, 'fsdk'):
+        if self.temporary and getattr(self, 'service', None) and hasattr(self, 'fsdk'):
             try:
-                self.fsdk.service_registry.remove_service(self.service_definition.id)
+                self.fsdk.service_registry.remove_service(self.service.id)
             except Exception:
-                # Ignore errors during cleanup (e.g., if FastSDK is already destroyed)
                 pass
             self.temporary = False