digitalkin 0.1.1__tar.gz → 0.2.0__tar.gz

{digitalkin-0.1.1 → digitalkin-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: digitalkin
-Version: 0.1.1
+Version: 0.2.0
 Summary: SDK to build kin used in DigitalKin
 Author-email: "DigitalKin.ai" <contact@digitalkin.ai>
 License: Attribution-NonCommercial-ShareAlike 4.0 International
@@ -452,25 +452,26 @@ Classifier: License :: Other/Proprietary License
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: digitalkin-proto>=0.0.8
+Requires-Dist: digitalkin-proto>=0.1.5
 Requires-Dist: grpcio-health-checking>=1.71.0
 Requires-Dist: grpcio-reflection>=1.71.0
 Requires-Dist: grpcio-status>=1.71.0
-Requires-Dist: pydantic>=2.10.6
+Requires-Dist: pydantic>=2.11.3
 Provides-Extra: dev
 Requires-Dist: pytest>=8.3.4; extra == "dev"
-Requires-Dist: pytest-asyncio>=0.25.3; extra == "dev"
-Requires-Dist: pytest-cov>=6.0.0; extra == "dev"
-Requires-Dist: typos>=1.30.2; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.26.0; extra == "dev"
+Requires-Dist: pytest-cov>=6.1.0; extra == "dev"
+Requires-Dist: typos>=1.31.1; extra == "dev"
 Requires-Dist: ruff>=0.11.2; extra == "dev"
 Requires-Dist: mypy>=1.15.0; extra == "dev"
-Requires-Dist: pyright>=1.1.397; extra == "dev"
+Requires-Dist: pyright>=1.1.398; extra == "dev"
 Requires-Dist: pre-commit>=4.2.0; extra == "dev"
 Requires-Dist: bump2version>=1.0.1; extra == "dev"
 Requires-Dist: build>=1.2.2; extra == "dev"
 Requires-Dist: twine>=6.1.0; extra == "dev"
 Requires-Dist: cryptography>=44.0.2; extra == "dev"
 Requires-Dist: grpcio-testing>=1.71.0; extra == "dev"
+Requires-Dist: freezegun>=1.5.1; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: openai>=1.66.3; extra == "examples"
 Dynamic: license-file

digitalkin-0.2.0/examples/base_server/__init__.py

@@ -0,0 +1 @@
+"""Example of a (a)synchronous (in)secure gRPC server using DigitalKin's BaseServer."""

digitalkin-0.2.0/examples/base_server/mock/__init__.py

@@ -0,0 +1,5 @@
+"""Basic greeting service.
+
+This module contains the definition of the basic greeting service
+implemented using Protocol Buffers and gRPC.
+"""

digitalkin-0.2.0/examples/base_server/mock/mock_pb2.py

@@ -0,0 +1,39 @@
+# ruff: noqa
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: mock.proto
+# Protobuf Python Version: 5.29.0
+"""Generated protocol buffer code."""
+
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+
+_runtime_version.ValidateProtobufRuntimeVersion(_runtime_version.Domain.PUBLIC, 5, 29, 0, "", "mock.proto")
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(
+    b'\n\nmock.proto\x12\nhelloworld"\x1c\n\x0cHelloRequest\x12\x0c\n\x04name\x18\x01 \x01(\t"\x1d\n\nHelloReply\x12\x0f\n\x07message\x18\x01 \x01(\t2I\n\x07Greeter\x12>\n\x08SayHello\x12\x18.helloworld.HelloRequest\x1a\x16.helloworld.HelloReply"\x00\x42\x36\n\x1bio.grpc.examples.helloworldB\x0fHelloWorldProtoP\x01\xa2\x02\x03HLWb\x06proto3'
+)
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, "mock_pb2", _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+    _globals["DESCRIPTOR"]._loaded_options = None
+    _globals[
+        "DESCRIPTOR"
+    ]._serialized_options = b"\n\033io.grpc.examples.helloworldB\017HelloWorldProtoP\001\242\002\003HLW"
+    _globals["_HELLOREQUEST"]._serialized_start = 26
+    _globals["_HELLOREQUEST"]._serialized_end = 54
+    _globals["_HELLOREPLY"]._serialized_start = 56
+    _globals["_HELLOREPLY"]._serialized_end = 85
+    _globals["_GREETER"]._serialized_start = 87
+    _globals["_GREETER"]._serialized_end = 160
+# @@protoc_insertion_point(module_scope)

digitalkin-0.2.0/examples/base_server/mock/mock_pb2_grpc.py

@@ -0,0 +1,102 @@
+# ruff: noqa
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+
+import grpc
+
+import examples.base_server.mock.mock_pb2 as mock__pb2
+
+GRPC_GENERATED_VERSION = "1.70.0"
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f"The grpc package installed is at version {GRPC_VERSION},"
+        + f" but the generated code in mock_pb2_grpc.py depends on"
+        + f" grpcio>={GRPC_GENERATED_VERSION}."
+        + f" Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}"
+        + f" or downgrade your generated code using grpcio-tools<={GRPC_VERSION}."
+    )
+
+
+class GreeterStub(object):
+    """The greeting service definition."""
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.SayHello = channel.unary_unary(
+            "/helloworld.Greeter/SayHello",
+            request_serializer=mock__pb2.HelloRequest.SerializeToString,
+            response_deserializer=mock__pb2.HelloReply.FromString,
+            _registered_method=True,
+        )
+
+
+class GreeterServicer(object):
+    """The greeting service definition."""
+
+    def SayHello(self, request, context):
+        """Sends a greeting"""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details("Method not implemented!")
+        raise NotImplementedError("Method not implemented!")
+
+
+def add_GreeterServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+        "SayHello": grpc.unary_unary_rpc_method_handler(
+            servicer.SayHello,
+            request_deserializer=mock__pb2.HelloRequest.FromString,
+            response_serializer=mock__pb2.HelloReply.SerializeToString,
+        ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler("helloworld.Greeter", rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers("helloworld.Greeter", rpc_method_handlers)
+
+
+# This class is part of an EXPERIMENTAL API.
+class Greeter(object):
+    """The greeting service definition."""
+
+    @staticmethod
+    def SayHello(
+        request,
+        target,
+        options=(),
+        channel_credentials=None,
+        call_credentials=None,
+        insecure=False,
+        compression=None,
+        wait_for_ready=None,
+        timeout=None,
+        metadata=None,
+    ):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            "/helloworld.Greeter/SayHello",
+            mock__pb2.HelloRequest.SerializeToString,
+            mock__pb2.HelloReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True,
+        )

digitalkin-0.2.0/examples/base_server/server_async_insecure.py

@@ -0,0 +1,124 @@
+#!/usr/bin/env python3
+"""Example of an asynchronous insecure gRPC server using BaseServer."""
+
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+# Add parent directory to path to enable imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+from digitalkin.grpc_servers._base_server import BaseServer
+from digitalkin.grpc_servers.utils.models import SecurityMode, ServerConfig, ServerMode
+from examples.base_server.mock.mock_pb2 import DESCRIPTOR, HelloReply  # type: ignore
+from examples.base_server.mock.mock_pb2_grpc import (
+    Greeter,
+    add_GreeterServicer_to_server,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class AsyncGreeterImpl(Greeter):
+    """Asynchronous implementation of Greeter service."""
+
+    async def SayHello(self, request, context):  # noqa: N802
+        """Asynchronous implementation of SayHello method."""
+        logger.info(f"Received request object: {request}")
+        logger.info(f"Request attributes: {vars(request)}")
+        logger.info(f"Received request with name: {request.name}")
+
+        # If the name is still empty, try to get metadata from the context
+        name = request.name
+        if not name:
+            name = "unknown"
+            # Check context metadata
+            for key, value in context.invocation_metadata():
+                logger.info(f"Metadata: {key}={value}")
+                if key.lower() == "name":
+                    name = value
+
+        # Simulate some async work
+        await asyncio.sleep(0.1)
+
+        return HelloReply(message=f"Hello async, {name}!")
+
+
+class AsyncInsecureServer(BaseServer):
+    """Asynchronous insecure gRPC server implementation."""
+
+    def _register_servicers(self) -> None:
+        """Register servicers with the gRPC server."""
+        if self.server is None:
+            msg = "Server must be created before registering servicers"
+            raise RuntimeError(msg)
+
+        # Create and register the servicer
+        servicer = AsyncGreeterImpl()
+        self.register_servicer(
+            servicer,
+            add_GreeterServicer_to_server,
+            service_descriptor=DESCRIPTOR,
+        )
+        logger.info("Registered Async Greeter servicer")
+
+
+async def main_async() -> int:
+    """Run the asynchronous insecure server."""
+    server = None
+    try:
+        # Create server configuration
+        config = ServerConfig(
+            host="localhost",
+            port=50051,
+            mode=ServerMode.ASYNC,
+            security=SecurityMode.INSECURE,
+        )
+
+        # Create the server
+        server = AsyncInsecureServer(config)
+
+        # Use the async-specific start method
+        await server.start_async()
+
+        logger.info("Server started. Press Ctrl+C to stop.")
+
+        # Keep the server running until interrupted
+        await server.await_termination()
+
+    except KeyboardInterrupt:
+        # This inner handler will rarely be reached,
+        # as the KeyboardInterrupt usually breaks out of asyncio.run()
+        logger.info("Server stopping due to keyboard interrupt...")
+    except Exception as e:
+        logger.exception(f"Error running server: {e}")
+        return 1
+    finally:
+        # Clean up resources if server was started
+        if server is not None and server.server is not None:
+            await server.stop_async()
+
+    return 0
+
+
+def main():
+    """Run the async main function."""
+    try:
+        return asyncio.run(main_async())
+    except KeyboardInterrupt:
+        # This is the primary KeyboardInterrupt handler
+        logger.info("Server stopped by keyboard interrupt")
+        return 0  # Clean exit
+    except Exception as e:
+        logger.exception(f"Fatal error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

digitalkin-0.2.0/examples/base_server/server_async_secure.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Example of an asynchronous secure gRPC server using BaseServer with TLS."""
+
+import asyncio
+import logging
+import sys
+from pathlib import Path
+
+# Add parent directory to path to enable imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+from digitalkin.grpc_servers._base_server import BaseServer
+from digitalkin.grpc_servers.utils.models import (
+    SecurityMode,
+    ServerConfig,
+    ServerCredentials,
+    ServerMode,
+)
+from examples.base_server.mock.mock_pb2 import DESCRIPTOR, HelloReply  # type: ignore
+from examples.base_server.mock.mock_pb2_grpc import (
+    Greeter,
+    add_GreeterServicer_to_server,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class AsyncGreeterImpl(Greeter):
+    """Asynchronous implementation of Greeter service."""
+
+    async def SayHello(self, request, context):  # noqa: N802
+        """Asynchronous implementation of SayHello method."""
+        logger.info(f"Received request object: {request}")
+        logger.info(f"Request attributes: {vars(request)}")
+        logger.info(f"Received request with name: {request.name}")
+
+        # If the name is still empty, try to get metadata from the context
+        name = request.name
+        if not name:
+            name = "unknown"
+            # Check context metadata
+            for key, value in context.invocation_metadata():
+                logger.info(f"Metadata: {key}={value}")
+                if key.lower() == "name":
+                    name = value
+
+        # Simulate some async work
+        await asyncio.sleep(0.1)
+
+        return HelloReply(message=f"Hello secure async, {name}!")
+
+
+class AsyncSecureServer(BaseServer):
+    """Asynchronous secure gRPC server implementation."""
+
+    def _register_servicers(self) -> None:
+        """Register servicers with the gRPC server."""
+        if self.server is None:
+            msg = "Server must be created before registering servicers"
+            raise RuntimeError(msg)
+
+        # Create and register the servicer
+        servicer = AsyncGreeterImpl()
+        self.register_servicer(
+            servicer,
+            add_GreeterServicer_to_server,
+            service_descriptor=DESCRIPTOR,
+        )
+        logger.info("Registered Async Greeter servicer")
+
+
+async def main_async() -> int:
+    """Run the asynchronous secure server."""
+    try:
+        # Path to certificate files
+        cert_dir = Path(__file__).parent.parent.parent / "certs"
+
+        # Check if certificates exist
+        if not cert_dir.exists() or not (cert_dir / "server.key").exists():
+            logger.error("Certificate files not found. Please generate them first.")
+            logger.info("Run the generate_certificates.py script to create certificates.")
+            return 1
+
+        # Create server configuration with security credentials
+        config = ServerConfig(
+            host="localhost",
+            port=50051,
+            mode=ServerMode.ASYNC,
+            security=SecurityMode.SECURE,
+            credentials=ServerCredentials(
+                server_key_path=cert_dir / "server.key",
+                server_cert_path=cert_dir / "server.crt",
+                # For mTLS (mutual TLS with client authentication), uncomment:
+                # root_cert_path=cert_dir / "ca.crt",  # noqa: ERA001
+            ),
+        )
+
+        # Create and start the server
+        server = AsyncSecureServer(config)
+        # Use the async-specific start method
+        await server.start_async()
+
+        logger.info("Server started. Press Ctrl+C to stop.")
+
+        # Keep the server running until interrupted
+        await server.await_termination()
+
+    except KeyboardInterrupt:
+        # This inner handler will rarely be reached,
+        # as the KeyboardInterrupt usually breaks out of asyncio.run()
+        logger.info("Server stopping due to keyboard interrupt...")
+    except Exception as e:
+        logger.exception(f"Error running server: {e}")
+        return 1
+    finally:
+        # Clean up resources if server was started
+        if server is not None and server.server is not None:
+            await server.stop_async()
+
+    return 0
+
+
+def main():
+    """Run the async main function."""
+    try:
+        return asyncio.run(main_async())
+    except KeyboardInterrupt:
+        # This is the primary KeyboardInterrupt handler
+        logger.info("Server stopped by keyboard interrupt")
+        return 0  # Clean exit
+    except Exception as e:
+        logger.exception(f"Fatal error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

digitalkin-0.2.0/examples/base_server/server_sync_insecure.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Example of a synchronous insecure gRPC server using BaseServer."""
+
+import logging
+import sys
+from pathlib import Path
+
+# Add parent directory to path to enable imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+from digitalkin.grpc_servers._base_server import BaseServer
+from digitalkin.grpc_servers.utils.models import SecurityMode, ServerConfig, ServerMode
+from examples.base_server.mock.mock_pb2 import DESCRIPTOR, HelloReply  # type: ignore
+from examples.base_server.mock.mock_pb2_grpc import (
+    Greeter,
+    add_GreeterServicer_to_server,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class SyncGreeterServicer(Greeter):
+    """Synchronous implementation of Greeter service."""
+
+    def SayHello(self, request, context):  # noqa: N802
+        """Implementation of SayHello method."""
+        logger.info(f"Received request object: {request}")
+        logger.info(f"Request attributes: {vars(request)}")
+        logger.info(f"Received request with name: {request.name}")
+
+        # If the name is still empty, try to get metadata from the context
+        name = request.name
+        if not name:
+            name = "unknown"
+            # Check context metadata
+            for key, value in context.invocation_metadata():
+                logger.info(f"Metadata: {key}={value}")
+                if key.lower() == "name":
+                    name = value
+
+        return HelloReply(message=f"Hello, {name}!")
+
+
+class SyncInsecureServer(BaseServer):
+    """Synchronous insecure gRPC server implementation."""
+
+    def _register_servicers(self) -> None:
+        """Register servicers with the gRPC server."""
+        if self.server is None:
+            msg = "Server must be created before registering servicers"
+            raise RuntimeError(msg)
+
+        # Create and register the servicer
+        servicer = SyncGreeterServicer()
+        self.register_servicer(
+            servicer,
+            add_GreeterServicer_to_server,
+            service_descriptor=DESCRIPTOR,
+        )
+        logger.info("Registered Greeter servicer")
+
+
+def main() -> int:
+    """Run the synchronous insecure server."""
+    try:
+        # Create server configuration
+        config = ServerConfig(
+            host="localhost",
+            port=50051,
+            mode=ServerMode.SYNC,
+            security=SecurityMode.INSECURE,
+            max_workers=10,
+        )
+
+        # Create and start the server
+        server = SyncInsecureServer(config)
+        server.start()
+
+        logger.info("Server started. Press Ctrl+C to stop.")
+
+        # Keep the server running until interrupted
+        try:
+            server.wait_for_termination()
+        except KeyboardInterrupt:
+            logger.info("Server stopping due to keyboard interrupt...")
+        finally:
+            server.stop()
+
+    except Exception as e:
+        logger.exception(f"Error running server: {e}")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

digitalkin-0.2.0/examples/base_server/server_sync_secure.py

@@ -0,0 +1,121 @@
+#!/usr/bin/env python3
+"""Example of a synchronous secure gRPC server using BaseServer with TLS."""
+
+import logging
+import sys
+from pathlib import Path
+
+# Add parent directory to path to enable imports
+sys.path.insert(0, str(Path(__file__).parent.parent.parent.parent))
+
+from digitalkin.grpc_servers._base_server import BaseServer
+from digitalkin.grpc_servers.utils.models import (
+    SecurityMode,
+    ServerConfig,
+    ServerCredentials,
+    ServerMode,
+)
+from examples.base_server.mock.mock_pb2 import DESCRIPTOR, HelloReply  # type: ignore
+from examples.base_server.mock.mock_pb2_grpc import (
+    Greeter,
+    add_GreeterServicer_to_server,
+)
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+class SyncGreeterServicer(Greeter):
+    """Synchronous implementation of Greeter service."""
+
+    def SayHello(self, request, context):  # noqa: N802
+        """Implementation of SayHello method."""
+        logger.info(f"Received request object: {request}")
+        logger.info(f"Request attributes: {vars(request)}")
+        logger.info(f"Received request with name: {request.name}")
+
+        # If the name is still empty, try to get metadata from the context
+        name = request.name
+        if not name:
+            name = "unknown"
+            # Check context metadata
+            for key, value in context.invocation_metadata():
+                logger.info(f"Metadata: {key}={value}")
+                if key.lower() == "name":
+                    name = value
+
+        return HelloReply(message=f"Hello secure, {name}!")
+
+
+class SyncSecureServer(BaseServer):
+    """Synchronous secure gRPC server implementation."""
+
+    def _register_servicers(self) -> None:
+        """Register servicers with the gRPC server."""
+        if self.server is None:
+            msg = "Server must be created before registering servicers"
+            raise RuntimeError(msg)
+
+        # Create and register the servicer
+        servicer = SyncGreeterServicer()
+        self.register_servicer(
+            servicer,
+            add_GreeterServicer_to_server,
+            service_descriptor=DESCRIPTOR,
+        )
+        logger.info("Registered Greeter servicer")
+
+
+def main() -> int:
+    """Run the synchronous secure server."""
+    try:
+        # Path to certificate files
+        cert_dir = Path(__file__).parent.parent.parent / "certs"
+        # Check if certificates exist
+        if not cert_dir.exists() or not (cert_dir / "server.key").exists():
+            logger.error("Certificate files not found. Please generate them first.")
+            logger.info("Run the generate_certificates.py script to create certificates.")
+            return 1
+
+        # Create server configuration with security credentials
+        config = ServerConfig(
+            host="localhost",
+            port=50051,
+            mode=ServerMode.SYNC,
+            security=SecurityMode.SECURE,
+            credentials=ServerCredentials(
+                server_key_path=cert_dir / "server.key",
+                server_cert_path=cert_dir / "server.crt",
+                # For mTLS (mutual TLS with client authentication), uncomment:
+                # root_cert_path=cert_dir / "ca.crt",  # noqa: ERA001
+            ),
+            max_workers=10,
+        )
+
+        # Create and start the server
+        server = SyncSecureServer(config)
+        server.start()
+
+        logger.info("Secure server started. Press Ctrl+C to stop.")
+
+        # Keep the server running until interrupted
+        try:
+            server.wait_for_termination()
+        except KeyboardInterrupt:
+            logger.info("Server stopping due to keyboard interrupt...")
+        finally:
+            server.stop()
+
+    except Exception as e:
+        logger.exception(f"Error running server: {e}")
+        return 1
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())