modulith 0.1.0__py3-none-any.whl

modulith/__init__.py

@@ -0,0 +1 @@
+from .modulith import Modulith

modulith/cli/login.py

@@ -0,0 +1,16 @@
+import typer
+from modulith.mns.login import login
+
+
+login_app = typer.Typer()
+
+@login_app.command("login")
+def login_command():
+    auth_token = typer.prompt("Authentication Token")
+
+    try:
+        username = login(auth_token)
+        typer.echo("✅ Login successful")
+        typer.echo(f"Username: {username}")
+    except ValueError as e:
+        typer.echo(e)

modulith/cli/logout.py

@@ -0,0 +1,10 @@
+import typer
+import keyring
+
+
+logout_app = typer.Typer()
+
+@logout_app.command("logout")
+def logout_command():
+    keyring.delete_password("modulith", "api_key")
+    typer.echo("✅ Logout successful. Authentication token removed.")

modulith/cli/main.py

@@ -0,0 +1,18 @@
+import typer
+from .signup import singup_app
+from .login import login_app
+from .logout import logout_app
+from .whoami import whoami_app
+from .serve import serve_app
+from .module.resolve import resolve_module_app  
+from .module.workload import workload_module_app
+
+
+app = typer.Typer()
+app.add_typer(login_app)
+app.add_typer(logout_app)
+app.add_typer(singup_app)
+app.add_typer(whoami_app)
+app.add_typer(serve_app)
+app.add_typer(resolve_module_app, name="module")
+app.add_typer(workload_module_app, name="module")

modulith/cli/module/resolve.py

@@ -0,0 +1,16 @@
+import typer
+from modulith.mns.module.resolve import resolve_module
+
+
+resolve_module_app = typer.Typer()
+
+@resolve_module_app.command("resolve")
+def resolve_command():
+    repository = typer.prompt("Repository")
+    token = typer.prompt("Authentication Token", hide_input=True)
+    validate_url = typer.confirm("Validate URL?", default=True)
+    try:
+        urls = resolve_module(repository, token, validate_url)
+        typer.echo(f"Module URLs: {urls}")
+    except ValueError as e:
+        typer.echo(f"Failed to resolve module: {str(e)}")

modulith/cli/module/workload.py

@@ -0,0 +1,20 @@
+import typer
+from modulith.mns.module.workload import workload_module
+
+
+workload_module_app = typer.Typer()
+
+@workload_module_app.command("workload")
+def workload_command(
+    repo: str = typer.Argument(..., help="Repository"),
+    token: str = typer.Option(None, help="Authentication Token", prompt=True, hide_input=True),
+    validate_url: bool = typer.Option(True, help="Validate URL?"),
+):
+    repo = typer.prompt("Repository") if not repo else repo
+    token = typer.prompt("Authentication Token", hide_input=True) if not token else token
+    validate_url = typer.confirm("Validate URL?", default=True) if validate_url is None else validate_url
+    try:
+        results = workload_module(repo, token, validate_url)
+        typer.echo(f"Module Workload: {results}")
+    except ValueError as e:
+        typer.echo(f"Failed to retrieve workload: {str(e)}")

modulith/cli/serve.py

@@ -0,0 +1,179 @@
+import os
+import sys
+import typer
+import keyring
+import importlib
+from typing import Literal
+from modulith import Modulith
+from typing import Annotated, Optional
+from modulith.utils.tunnels import start_tunnel
+from modulith.server import create_fastapi_server
+from modulith.mns.guest_signup import guest_signup
+from modulith.mns.module.register import register_module
+from modulith.utils.connections import wait_for_connection
+
+
+def load_module(module_ref: str):
+    variable_name = None
+    if ":" in module_ref:
+        module_ref, variable_name = module_ref.split(":")
+    
+    # Add the current working directory to sys.path if it's not already there
+    if os.getcwd() not in sys.path:
+        sys.path.insert(0, os.getcwd())
+    
+    mod = importlib.import_module(module_ref)
+    if variable_name is None:
+        for name in ("module", "app", "service", "tool"):
+            if hasattr(mod, name):
+                variable_name = name
+                break
+
+    if variable_name is None:
+        raise ValueError(f"Module reference '{module_ref}' does not specify a variable name and no default variable ('module', 'app', 'service', or 'tool') was found. Please specify the variable name explicitly, e.g. '{module_ref}:variable_name'.")
+
+    module = getattr(mod, variable_name)
+    if isinstance(module, Modulith):
+        return module
+    
+    raise ValueError(f"Module '{module_ref}' is not an instance of Modulith.")
+
+
+serve_app = typer.Typer()
+@serve_app.command("serve")
+def serve_command(
+    module_path: Annotated[
+        str,
+        typer.Argument(
+            ...,
+            help="Python module path, e.g. 'calculator.module'",
+        ),
+    ],
+    port: Annotated[
+        int,
+        typer.Option("--port", help="Port to bind the server to."),
+    ] = 8000,
+    host: Annotated[
+        str,
+        typer.Option("--host", help="Host to bind the server to. Use 'localhost' for tunnel providers to work properly."),
+    ] = "localhost",
+    tunnel: Annotated[
+        Optional[Literal["instatunnel", "cloudflare", "ngrok", "any"]],
+        typer.Option("--tunnel", help="Tunnel provider to use for public exposure. Options: 'instatunnel', 'cloudflare', 'ngrok', 'any'. If not specified, the server will not be exposed publicly."),
+    ] = "any",
+    public: Annotated[
+        bool,
+        typer.Option("--public", help="Expose the module publicly."),
+    ] = False,
+    burst_limit: Annotated[
+        Optional[int],
+        typer.Option("--burst-limit", help="Maximum number of concurrent requests allowed for public access."),
+    ] = None,
+    rate_limit: Annotated[
+        Optional[int],
+        typer.Option("--rate-limit", help="Maximum number of requests per minute allowed for public access."),
+    ] = None,
+    max_queue_size: Annotated[
+        int,
+        typer.Option("--max-queue-size", help="Maximum number of requests to queue when the server is under heavy load. Requests beyond this limit will be rejected with a 503 error."),
+    ] = 10000,
+    num_workers: Annotated[
+        Optional[int],
+        typer.Option("--num-workers", help="Number of worker processes to handle requests. If not specified, it will default to the number of CPU cores."),
+    ] = None,
+    timeout: Annotated[
+        Optional[float],
+        typer.Option("--timeout", help="Maximum time in seconds to allow a request to be processed before timing out. If not specified, there will be no timeout."),
+    ] = None,
+    logging_path: Annotated[
+        str,
+        typer.Option("--logging-path", help="Path to the log file for the server. Logs will be rotated daily."),
+    ] = "logs/server.log",
+    auth_token: Annotated[
+        Optional[str],
+        typer.Option("--auth-token", help="Your authentication token. If not provided, a token will be generated and displayed in the console."),
+    ] = None,
+    no_tunnel: Annotated[
+        bool,
+        typer.Option("--no-tunnel", help="Do not establish a tunnel even if the --tunnel option is specified. This is useful for testing the server without exposing it publicly."),
+    ] = False,
+    skip_registration: Annotated[
+        bool,
+        typer.Option("--skip-registration", help="Skip registering the module to the Modulith Network Service."),
+    ] = False,
+):
+    module: Modulith = load_module(module_path)
+
+    local_url = f"http://{host}:{port}"
+    thread = create_fastapi_server(
+        module=module,
+        host=host,
+        port=port,
+        auth_token=auth_token,
+        public=public,
+        burst_limit=burst_limit,
+        rate_limit=rate_limit,
+        max_queue_size=max_queue_size,
+        num_workers=num_workers,
+        timeout=timeout,
+        logging_path=logging_path,
+    )
+    # Wait for server to be up
+    if not wait_for_connection(local_url):
+        raise RuntimeError(f"❌ Failed to start server at port {port}")
+    
+    public_url = None
+    repository = None
+    if not no_tunnel:
+        typer.echo("🚀 Establishing tunnel...")
+        tunnel_instance = start_tunnel(local_port=port, provider=tunnel)
+        public_url = tunnel_instance.public_url
+        
+    guest_token = None
+    if not skip_registration and public_url:
+        typer.echo("🚀 Authenticating...")
+        auth_token = auth_token or os.environ.get("MODULITH_API_TOKEN") or keyring.get_password("modulith", "api_key")
+        if auth_token is None:
+            auth_token = guest_signup()
+            guest_token = auth_token
+
+        typer.echo("🚀 Registering module...")
+        repository = register_module(modulename=module.name, public_url=public_url, public=public, token=auth_token)
+
+    if guest_token:
+         typer.echo()
+         typer.echo(f"🔑 Your authentication token: {guest_token}")
+
+    typer.echo()
+    typer.echo(f"🌐 Module '{module.name}' is live:")
+    if repository:
+        typer.echo(f"- Repository: {repository}")
+    if public_url:
+        typer.echo(f"- Public URL: {public_url}")
+    typer.echo(f"- Local URL: {local_url}")
+    typer.echo()
+
+    typer.echo("⚙️ Capabilities:")
+    for name, capability in module.capabilities.items():
+        typer.echo(f"- {name}{capability.signature}")
+    typer.echo()
+
+    if public and (burst_limit or rate_limit):
+        typer.echo("⚡ Public access limits:")
+        if rate_limit:
+            typer.echo(f"- Rate limit: {rate_limit} requests per minute")
+        if burst_limit:
+            typer.echo(f"- Burst limit: {burst_limit} concurrent requests")
+        typer.echo()
+
+    typer.echo("🛑 Press Ctrl+C to stop")
+
+    try:
+        while thread.is_alive():
+            thread.join(timeout=1)
+    except KeyboardInterrupt:
+        print("🛑 Shutting down...")
+        if tunnel_instance:
+            tunnel_instance.stop()
+        # TODO: deregister model from MNS
+        # print("✅ Shutdown complete")

modulith/cli/signup.py

@@ -0,0 +1,20 @@
+import typer
+from modulith.mns.signup import sign_up
+
+
+singup_app = typer.Typer()
+
+@singup_app.command("signup")
+def signup_command():
+    email = typer.prompt("Email")
+    username = typer.prompt("Username")
+    password = typer.prompt("Password", hide_input=True)
+
+    try:
+        token = sign_up(email, username, password)
+        typer.echo("✅ Signup successful")
+        typer.echo(f"Email: {email}")
+        typer.echo(f"Username: {username}")
+        typer.echo(f"Authentication key: {token}")
+    except ValueError as e:
+        typer.echo(f"Failed to signup: {str(e)}")

modulith/cli/whoami.py

@@ -0,0 +1,19 @@
+import typer
+import keyring
+from modulith.mns.whoami import whoami
+
+
+whoami_app = typer.Typer()
+
+@whoami_app.command("whoami")
+def whoami_command():
+    api_key = keyring.get_password("modulith", "api_key")
+    if not api_key:
+        typer.echo("No authentication token found. Please login first.")
+        raise typer.Exit(code=1)
+
+    try:
+        username = whoami(api_key)
+        typer.echo(f"Authenticated as: {username}")
+    except ValueError as e:
+        typer.echo(e)

modulith/dataclasses/__init__.py

@@ -0,0 +1 @@
+from .capability import Capability, LocalCapability, RemoteCapability

modulith/dataclasses/capability.py

@@ -0,0 +1,176 @@
+import time
+import atexit
+import inspect
+import requests
+import threading
+from typing import Callable, Any
+from modulith.mns.module import resolve_module
+
+
+class Capability:
+    def __init__(
+        self, 
+        name: str,
+        signature: str,
+        docstring: str,
+        allow_cache: bool = True,
+        max_concurrency: int | None = None,
+    ):
+        self.name = name
+        self.signature = signature
+        self.docstring = docstring
+        self.allow_cache = allow_cache
+        self.max_concurrency = max_concurrency 
+
+    def execute(self, kwargs: dict) -> Any:
+        raise NotImplementedError("Subclasses must implement the execute method.")
+
+class LocalCapability(Capability):
+    def __init__(
+        self, 
+        name: str,
+        func: Callable[[dict], Any],
+        allow_cache: bool = True,
+        max_concurrency: int | None = None,
+    ):
+        super().__init__(
+            name=name,
+            signature=str(inspect.signature(func)),
+            docstring=inspect.getdoc(func),
+            allow_cache=allow_cache,
+            max_concurrency=max_concurrency,
+        )
+        self.func = func
+
+    def execute(self, kwargs: dict | None = None) -> Any:
+        kwargs = kwargs or {}
+        return self.func(**kwargs)
+
+class RemoteCapability(Capability):
+    def __init__(
+        self, 
+        name: str,
+        repository: str,
+        signature: str,
+        docstring: str,
+        urls: list[str],
+        allow_cache: bool,
+        access_token: str,
+    ):
+        super().__init__(
+            name=name,
+            signature=signature,
+            docstring=docstring,
+            allow_cache=allow_cache,
+            max_concurrency=1,
+        )
+
+        self.repository = repository
+        self.access_token = access_token
+        self.urls = urls
+
+        self.running_index = 0 # Index for round-robin load balancing
+        self.last_check_time = time.monotonic() # Timestamp of the last URLs and quota check
+
+        self.shutdown_event = threading.Event()
+        self.wake_event = threading.Event()
+
+        self.routine_worker = threading.Thread(target=self._routine_loop, daemon=True)
+        self.routine_worker.start()
+        self.wake_event.set()  # Trigger the routine loop to perform the initial URLs and quota check immediately
+        
+        atexit.register(self._shutdown)
+
+    def _shutdown(self):
+        # Signal all threads to shut down
+        self.shutdown_event.set()
+        # Wait for the routine worker to finish
+        self.routine_worker.join()
+
+    def _routine_loop(self):
+        while not self.shutdown_event.is_set():
+            self.wake_event.wait(timeout=60)  # Wait for either timeout or wake signal
+            # Update list of accessible URLs
+            remote_urls = resolve_module(self.repository, self.access_token)
+            accessible_urls = []
+            for url in remote_urls:
+                response = requests.get(f"{url}/{self.name}", headers={"Authorization": f"Bearer {self.access_token}"} if self.access_token else {})
+                if response.status_code == 200:
+                    accessible_urls.append(url)
+            with threading.Lock():
+                self.urls = accessible_urls
+                # Ensure that running_index is within the bounds of the updated URLs list
+                if self.running_index >= len(self.urls):
+                    self.running_index = 0
+            self.wake_event.clear()  # Clear the wake event after processing
+                        
+    def execute(self, kwargs: dict | None = None, timeout: float | None = 10) -> Any:
+        kwargs = kwargs or {}
+        # If URLs are being updated, wait until the update is done
+        while self.wake_event.is_set():
+            time.sleep(0.1)
+        if len(self.urls) == 0:
+            raise Exception(f"No accessible module URLs. Please check the '{self.repository}' repository and your access token.")
+        
+        for attempt in range(2):
+            # Get url for remote call with simple round-robin load balancing
+            with threading.Lock():
+                url = self.urls[self.running_index]
+                self.running_index = (self.running_index + 1) % len(self.urls)
+            try:
+                result = self.remote_call(
+                    url=url,
+                    endpoint=self.name,
+                    access_token=self.access_token,
+                    kwargs=kwargs,
+                    timeout=timeout,
+                )
+                break   # Break after successful execution
+            except Exception as e:
+                if attempt == 0:
+                    self.wake_event.set()  # Wake up the routine loop to refresh URLs and quotas on the first failure
+                    while self.wake_event.is_set():
+                        time.sleep(0.1)  # Wait for the routine loop to update the URLs before retrying
+                    if len(self.urls) == 0:
+                        raise Exception(f"No accessible module URLs. Please check the '{self.repository}' repository and your access token.")
+                    continue  # Retry on the first attempt
+                raise e
+        return result
+
+    @staticmethod
+    def remote_call(
+        url: str, 
+        endpoint: str, 
+        access_token: str, 
+        kwargs: dict, 
+        timeout: float | None = 10,
+    ) -> Any:
+        """
+        Perform a remote call to the specified URL and endpoint with the given access token and arguments.
+        Retry the call if it fails due to rate limiting (HTTP 429) or server queue full (HTTP 503), until it succeeds or the optional timeout is reached.
+        """
+        start_time = time.monotonic()
+        while True:
+            # Timeout check
+            if timeout:
+                elapsed_time = time.monotonic() - start_time
+                if elapsed_time > timeout:
+                    raise TimeoutError(f"Remote call to {url}/{endpoint} timed out after {timeout} seconds.")
+
+            # Make the remote call
+            headers = {"Authorization": f"Bearer {access_token}"} if access_token else {}
+            response = requests.post(f"{url}/{endpoint}", json=kwargs, headers=headers, timeout=timeout)
+
+            if response.status_code == 200:
+                return response.json()["output"]
+            elif response.status_code == 429:
+                # Rate limit exceeded, wait and keep retry until timeout or success
+                retry_after = response.json().get("retry_after", 1)
+                time.sleep(retry_after)
+                continue
+            elif response.status_code == 503:
+                # Server queue full, wait and keep retry until timeout or success
+                time.sleep(1)
+                continue
+            else:
+                raise Exception(f"Remote call failed with status code {response.status_code}: {response.text}")

modulith/global_variables.py

@@ -0,0 +1 @@
+MNS_URL = "https://0q4dl5ht80.execute-api.ap-southeast-2.amazonaws.com/prod"

modulith/mns/guest_signup.py

@@ -0,0 +1,13 @@
+import requests
+from modulith.global_variables import MNS_URL
+
+
+def guest_signup() -> str:
+    from .login import login
+    response = requests.post(f"{MNS_URL}/guest_sign_up", json={})
+    if response.status_code == 200:
+        token = response.json().get("token")
+        # Automatically log in the user after successful sign-up
+        login(token)
+        return token
+    raise ValueError("Failed to sign up as guest")

modulith/mns/login.py

@@ -0,0 +1,11 @@
+import keyring
+
+
+def login(api_key: str) -> str:
+    from .whoami import whoami
+    try:
+        username = whoami(api_key)
+        keyring.set_password("modulith", "api_key", api_key)
+        return username
+    except ValueError as e:
+        raise ValueError(f"Login failed: {e}")

modulith/mns/module/__init__.py

@@ -0,0 +1,2 @@
+from .resolve import resolve_module
+from .workload import workload_module

modulith/mns/module/register.py

@@ -0,0 +1,17 @@
+import requests
+from modulith.global_variables import MNS_URL
+
+
+def register_module(modulename: str, public_url: str, public: bool, token: str = None) -> str:
+    response = requests.post(
+        f"{MNS_URL}/register_module",
+        json={
+            "modulename": modulename,
+            "url": public_url,
+            "public": public,
+            "token": token,
+        },
+    )
+    if response.status_code == 200:
+        return response.json()["repo"]
+    raise ValueError(f"Failed to register module: {response.text}")

modulith/mns/module/resolve.py

@@ -0,0 +1,13 @@
+import requests
+from modulith.global_variables import MNS_URL
+
+
+def resolve_module(repository: str, token: str = None, validate_url: bool = True) -> list[str]:
+    response = requests.get(f"{MNS_URL}/resolve_module", json={
+        "repository": repository,
+        "token": token,
+        "validate_url": validate_url,
+    })
+    if response.status_code == 200:
+        return response.json().get("urls", [])
+    raise ValueError(f"Failed to resolve module: {response.text}")

modulith/mns/module/workload.py

@@ -0,0 +1,16 @@
+import requests
+from .resolve import resolve_module
+from modulith.global_variables import MNS_URL
+
+
+def workload_module(repository: str, token: str = None, validate_url: bool = True) -> list[str]:
+    urls = resolve_module(repository, token, validate_url)
+    
+    results = {}
+    for url in urls:
+        response = requests.get(f"{url}/workload")
+        if response.status_code == 200:
+            results[url] = response.json()
+        else:
+            results[url] = {"error": f"Failed to retrieve workload: {response.text}"}
+    return results

modulith/mns/signup.py

@@ -0,0 +1,22 @@
+import requests
+from modulith.global_variables import MNS_URL
+
+
+def sign_up(
+    email: str,
+    username: str,
+    password: str,
+) -> str:
+    from .login import login
+    payload = {
+        "email": email,
+        "password": password,
+        "username": username,
+    }
+    response = requests.post(f"{MNS_URL}/sign_up", json=payload)
+    if response.status_code == 200:
+        token = response.json().get("token")
+        # Automatically log in the user after successful sign-up
+        login(token)
+        return token
+    raise ValueError(f"Failed to sign up: {response.text}")

modulith/mns/whoami.py

@@ -0,0 +1,10 @@
+import requests
+from modulith.global_variables import MNS_URL
+
+
+def whoami(api_key: str) -> str:
+    response = requests.get(f"{MNS_URL}/whoami", json={"token": api_key})
+    if response.status_code == 200:
+        username = response.json()["username"]
+        return username
+    raise ValueError(f"Failed to retrieve user information: {response.text.replace('Internal Server Error: ', '')}")