platform-ext-utils 0.0.1__py3-none-any.whl

platform_ext_utils-0.0.1.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: platform-ext-utils
+Version: 0.0.1
+Summary: Shared utility library for Cloudscaile extension features, providing Kafka integration and utilities
+Author: Cloudscaile Engineering
+License: Apache-2.0
+Keywords: cloudscaile,kafka,extensions,utilities
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: confluent-kafka>=2.4
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: httpx>=0.25
+Dynamic: license-file
+
+# platform-ext-utils
+
+Shared utility library for Cloudscaile extension features, providing Kafka integration, environment configuration management, and external connectivity utilities.
+
+## Features
+
+- **Kafka Service**: Simplified Kafka producer and consumer interface with Sasl support
+- **Environment Management**: Centralized configuration via environment variables
+- **Logger**: Pre-configured logging for consistent application logs
+- **External Connectivity**: Internal HTTP client instances for inter-service communication
+
+## Installation
+
+```bash
+pip install platform-ext-utils
+```
+
+## Requirements
+
+- Python >= 3.9
+- confluent-kafka >= 2.4
+- pydantic >= 2.0
+- pydantic-settings >= 2.0
+- httpx >= 0.25
+
+## Configuration
+
+All configuration is done via environment variables:
+
+```bash
+# Kafka Configuration
+KAFKA_REQUIRED=
+KAFKA_CLIENT_ID=
+KAFKA_BROKERS=
+KAFKA_GROUP_ID=
+KAFKA_CONSUMER_TOPIC=
+KAFKA_PRODUCER_TOPIC=
+
+# Optional: Kafka SASL Authentication
+KAFKA_SASL=
+KAFKA_SASL_USERNAME=
+KAFKA_SASL_PASSWORD=
+
+# Tenant Configuration
+TENANT_NAME=
+EXTENSION_NAME=
+```
+
+## Usage
+
+### Producing Messages
+
+```python
+from py_utils import produce_message
+
+produce_message(
+    {"event": "user_created", "userId": "123"},
+    topic="user-events"
+)
+```
+
+### Consuming Messages
+
+```python
+from py_utils import kafka_service
+
+def handle_message(event):
+    print("Received:", event)
+
+if kafka_service:
+    kafka_service.consume(callback=handle_message)
+```
+
+The callback receives:
+
+```python
+{
+  "queueName": "<topic>",
+  "partition": 0,
+  "offset": 42,
+  "message": "<decoded string>",
+  "timestamp": (<type>, <value>)
+}
+```
+
+### Using Logger
+
+```python
+from py_utils.utils.logger import logger
+
+logger.info("Application started")
+logger.error("An error occurred")
+```
+
+### External Connectivity
+
+```python
+from py_utils import internal_axios_instances
+
+# Use pre-configured HTTP clients for inter-service communication
+```
+
+## License
+
+Apache License 2.0
+
+## Author
+
+Cloudscaile Engineering

platform_ext_utils-0.0.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+platform_ext_utils-0.0.1.dist-info/licenses/LICENSE,sha256=y-NeOiY4Zrc6za4xKqeCyrfFhaVXYvTbvjsPq7xheyo,9803
+py_utils/__init__.py,sha256=1tOnIHzAdCTHfE1Vp6OV-y6PCYWHHceyOTJg96VBYP8,1984
+py_utils/extern_connect.py,sha256=pf8PXMSFddrUboEAsah7kXiUXyNqgpj0JOH7zapRslg,1464
+py_utils/kafka_service.py,sha256=sys_Kx5UmjTzIN-PlYAOIOx4SEEodThNq2Us2GfVuuI,3298
+py_utils/utils/envs.py,sha256=pZYZ4tt7e8Le-7yAl8fXzv-B1ovBgnzBK-f68Vad4no,3703
+py_utils/utils/logger.py,sha256=VyRxKs8i3Qq5RKgUqmwH5CnsXB5FeE4PZvAmkCWfzFo,429
+platform_ext_utils-0.0.1.dist-info/METADATA,sha256=kPlpPsBnuW4jlwW5zRgeEhcOnQUUu_Bef61XbJVAtBU,2751
+platform_ext_utils-0.0.1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+platform_ext_utils-0.0.1.dist-info/top_level.txt,sha256=TurY9TdpPVhVAzKr6GXCR9fBn3fQ6SC0QdC7IEyDWeo,9
+platform_ext_utils-0.0.1.dist-info/RECORD,,

platform_ext_utils-0.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

platform_ext_utils-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,178 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+Copyright 2026 Cloudscaile
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+    "License" shall mean the terms and conditions for use, reproduction,
+    and distribution as defined in Sections 1 through 9 of this document.
+
+    "Licensor" shall mean the copyright owner or entity authorized by
+    the copyright owner that is granting the License.
+
+    "Legal Entity" shall mean the union of the acting entity and all
+    other entities that control, are controlled by, or are under common
+    control with that entity. For the purposes of this definition,
+    "control" means (i) the power, direct or indirect, to cause the
+    direction or management of such entity, whether by contract or
+    otherwise, or (ii) ownership of fifty percent (50%) or more of the
+    outstanding shares, or (iii) beneficial ownership of such entity.
+
+    "You" (or "Your") shall mean an individual or Legal Entity exercising
+    permissions granted by this License.
+
+    "Source" form shall mean the preferred form for making modifications,
+    including but not limited to software source code, documentation
+    source, and configuration files.
+
+    "Object" form shall mean any form resulting from mechanical
+    transformation or translation of a Source form, including but
+    not limited to compiled object code, generated documentation,
+    and conversions to other media types.
+
+    "Work" shall mean the work of authorship, whether in Source or Object
+    form, made available under the License, as indicated by a copyright
+    notice that is included in or attached to the work (an example is
+    provided in the Appendix below).
+
+    "Derivative Works" shall mean any work, whether in Source or Object
+    form, that is based on (or derived from) the Work and for which the
+    editorial revisions, annotations, elaborations, or other modifications
+    represent, as a whole, an original work of authorship. For the purposes
+    of this License, Derivative Works shall not include works that remain
+    separable from, or merely link (or bind by name) to the interfaces of,
+    the Work and Derivative Works thereof.
+
+    "Contribution" shall mean any work of authorship, including
+    the original Work and any Derivative Works thereof, submitted to,
+    or received by, Licensor and intentionally submitted for inclusion
+    in, the Work by the copyright owner or by an individual or Legal
+    Entity authorized to submit on behalf of the copyright owner. For the
+    purposes of this definition, "submitted" means any form of electronic,
+    verbal, or written communication sent to the Licensor or its
+    representatives, including but not limited to communication on
+    electronic mailing lists, source code control systems, and issue
+    tracking systems that are managed by, or on behalf of, the Licensor
+    for the purpose of discussing and improving the Work, but excluding
+    communication that is conspicuously marked or otherwise designated
+    in writing by the copyright owner as "Not a Contribution."
+
+    "Contributor" shall mean Licensor and any Legal Entity on behalf of
+    whom a Contribution has been received by Licensor and subsequently
+    incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    copyright license to reproduce, prepare Derivative Works of,
+    publicly display, publicly perform, sublicense, and distribute the
+    Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of
+    this License, each Contributor hereby grants to You a perpetual,
+    worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+    (except as stated in this section) patent license to make, have made,
+    use, offer to sell, sell, import, and otherwise transfer the Work,
+    where such license applies only to those patent claims licensable
+    by such Contributor that are necessarily infringed by their
+    Contribution(s) alone or by combination of their Contribution(s)
+    with the Work to which such Contribution(s) was submitted. If You
+    institute patent litigation against any entity (including a
+    cross-claim or counterclaim in a lawsuit) alleging that the Work
+    or a Contribution incorporated within the Work constitutes direct
+    or contributory patent infringement, then any patent licenses
+    granted to You under this License for that Work shall terminate
+    as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the
+    Work or Derivative Works thereof in any medium, with or without
+    modifications, and in Source or Object form, provided that You
+    meet the following conditions:
+
+    (a) You must give any other recipients of the Work or
+        Derivative Works a copy of this License; and
+
+    (b) You must cause any modified files to carry prominent notices
+        stating that You changed the files; and
+
+    (c) You must retain, in the Source form of any Derivative Works
+        that You distribute, all copyright, patent, trademark, and
+        attribution notices from the Source form of the Work,
+        excluding those notices that do not pertain to any part of
+        the Derivative Works; and
+
+    (d) If the Work includes a "NOTICE" text file, then any
+        Derivative Works that You distribute must include a readable
+        copy of the attribution notices contained
+        within such NOTICE file, excluding those notices that do not
+        pertain to any part of the Derivative Works, in at least one
+        of the following places: within a NOTICE text file distributed
+        as part of the Derivative Works; within the Source form or
+        documentation, if provided along with the Derivative Works; or,
+        within a display generated by the Derivative Works, if and
+        wherever such third-party notices normally appear. The contents
+        of the NOTICE file are for informational purposes only and
+        do not modify the License. You may add Your own attribution
+        notices within Derivative Works that You distribute, alongside
+        or as an addendum to the NOTICE from the Work, provided that
+        such additional attribution notices cannot be construed as
+        modifying the License.
+
+    You may add Your own copyright statement to Your modifications and
+    may provide additional or different license terms and conditions
+    for use, reproduction, or distribution of Your modifications, or
+    for any such Derivative Works as a whole, provided Your use,
+    reproduction, and distribution of the Work otherwise complies with
+    the conditions of this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise,
+    any Contribution intentionally submitted for inclusion in the Work
+    by You to Licensor shall be under the terms and conditions of
+    this License, without any additional terms or conditions.
+    Notwithstanding the above, nothing herein shall supersede or modify
+    the terms of any separate license agreement you may have executed
+    with Licensor regarding such Contribution.
+
+6. Trademarks. This License does not grant permission to use the trade
+    names, trademarks, service marks, or product names of the Licensor,
+    except as required for reasonable and customary use in describing the
+    origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or
+    agreed to in writing, Licensor provides the Work (and each
+    Contributor provides its Contributions) on an "AS IS" BASIS,
+    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+    implied, including, without limitation, any warranties or conditions
+    of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+    PARTICULAR PURPOSE. You are solely responsible for determining the
+    appropriateness of using or redistributing the Work and assume any
+    risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory,
+    whether in tort (including negligence), contract, or otherwise,
+    unless required by applicable law (such as deliberate and grossly
+    negligent acts) or agreed to in writing, shall any Contributor be
+    liable to You for damages, including any direct, indirect, special,
+    incidental, or consequential damages of any character arising as a
+    result of this License or out of the use or inability to use the
+    Work (including but not limited to damages for loss of goodwill,
+    work stoppage, computer failure or malfunction, or any and all
+    other commercial damages or losses), even if such Contributor
+    has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing
+    the Work or Derivative Works thereof, You may choose to offer,
+    and charge a fee for, acceptance of support, warranty, indemnity,
+    or other liability obligations and/or rights consistent with this
+    License. However, in accepting such obligations, You may act only
+    on Your own behalf and on Your sole responsibility, not on behalf
+    of any other Contributor, and only if You agree to indemnify,
+    defend, and hold each Contributor harmless for any liability
+    incurred by, or claims asserted against, such Contributor by reason
+    of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

platform_ext_utils-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+py_utils

py_utils/__init__.py

@@ -0,0 +1,68 @@
+"""
+Copyright 2026 CloudScaile
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+
+import atexit
+from .utils.logger import logger
+from .utils.envs import envs as _envs  # internal use only
+from .kafka_service import KafkaService
+from .extern_connect import internal_axios_instances
+
+kafka_service = None
+
+# Initialize KafkaService only if required
+if _envs.KAFKA_REQUIRED:
+    try:
+        kafka_service = KafkaService(
+            client_id=_envs.KAFKA_CLIENT_ID,
+            brokers=_envs.KAFKA_BROKERS.split(","),
+            consumer_topic=_envs.KAFKA_CONSUMER_TOPIC,
+            group_id=_envs.KAFKA_GROUP_ID,
+            producer_topic=_envs.KAFKA_PRODUCER_TOPIC,
+        )
+        logger.info("✅ KafkaService initialized successfully")
+    except Exception as e:
+        logger.error(f"❌ Failed to initialize KafkaService: {e}")
+        kafka_service = None
+else:
+    logger.info("ℹ️ KafkaService not required as per configuration")
+
+def produce_message(message, topic=None):
+    if kafka_service is None:
+        logger.warning("⚠️ Kafka disabled. Skipping produce_message()")
+        return
+
+    try:
+        kafka_service.send_message(message, topic)
+    except Exception as e:
+        logger.error(f"❌ Failed to send Kafka message: {e}")
+
+
+def consume_messages(callback):
+    if kafka_service is None:
+        logger.warning("⚠️ Kafka disabled. Skipping consume_messages()")
+        return
+
+    try:
+        kafka_service.consume_messages(callback)
+    except Exception as e:
+        logger.error(f"❌ Kafka consumer stopped unexpectedly: {e}")
+
+@atexit.register
+def shutdown():
+    if kafka_service:
+        try:
+            kafka_service.disconnect()
+            logger.info("🛑 KafkaService disconnected cleanly")
+        except Exception as e:
+            logger.error(f"❌ Error during Kafka shutdown: {e}")
+
+__all__ = [
+    "produce_message",
+    "consume_messages",
+    "internal_axios_instances"
+]

py_utils/extern_connect.py

@@ -0,0 +1,64 @@
+"""
+Copyright 2026 CloudScaile
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+
+import os
+import httpx
+
+PLATFORM_URL = os.getenv("PLATFORM_URL")
+
+if not PLATFORM_URL:
+    raise RuntimeError("PLATFORM_URL env var not set")
+
+
+def _extract_headers(source):
+    """
+    Accepts:
+    - dict of headers
+    - request-like object with `.headers`
+    """
+    # Case 1: headers dict
+    if isinstance(source, dict):
+        return source
+
+    # Case 2: request-like object
+    if hasattr(source, "headers"):
+        return dict(source.headers)
+
+    raise TypeError(
+        "internal_axios_instances expects either a headers dict "
+        "or an object with a `.headers` attribute"
+    )
+
+
+def internal_axios_instances(source):
+    incoming = _extract_headers(source)
+
+    forward_headers = {}
+
+    # Authorization — required
+    auth = incoming.get("authorization")
+    if not auth:
+        raise RuntimeError("Authorization header missing in request")
+
+    forward_headers["Authorization"] = auth
+
+    # user-agent — optional but common
+    ua = incoming.get("user-agent")
+    if ua:
+        forward_headers["user-agent"] = ua
+
+    # x-tenant-id — optional (not implemented yet)
+    tenant = incoming.get("x-tenant-id")
+    if tenant:
+        forward_headers["x-tenant-id"] = tenant
+
+    return httpx.Client(
+        base_url=f"{PLATFORM_URL}/v1/portal",
+        headers=forward_headers,
+        timeout=10.0,
+    )

py_utils/kafka_service.py

@@ -0,0 +1,100 @@
+"""
+Copyright 2026 CloudScaile
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+
+from confluent_kafka import Producer, Consumer, KafkaError
+import json
+from .utils.logger import logger
+from .utils.envs import envs
+
+class KafkaService:
+    def __init__(self, client_id, brokers, consumer_topic, group_id, producer_topic):
+        self.producer_topic = producer_topic
+        self.consumer_topic = consumer_topic
+        self.group_id = group_id
+
+        # Base config
+        base_conf = {
+            "bootstrap.servers": brokers,
+            "client.id": client_id
+        }
+
+        # Security config
+        if envs.KAFKA_SASL:
+            sasl_conf = {
+                "security.protocol": "SASL_SSL",
+                "sasl.mechanism": "SCRAM-SHA-512",
+                "sasl.username": envs.KAFKA_SASL_USERNAME,
+                "sasl.password": envs.KAFKA_SASL_PASSWORD
+            }
+            base_conf.update(sasl_conf)
+
+        # Producer
+        self.producer = Producer(base_conf)
+
+        # Consumer configuration
+        consumer_conf = base_conf.copy()
+        consumer_conf.update({
+            "group.id": group_id,
+            "auto.offset.reset": "earliest",
+            "enable.auto.commit": False
+        })
+
+        # Create consumer only once
+        self.consumer_conf = consumer_conf
+        self.consumer = Consumer(consumer_conf)
+
+    def send_message(self, message: dict, topic: str):
+        try:
+            tenant_topic = f"{envs.TENANT_NAME}-{envs.EXTENSION_NAME}-{topic}"
+            payload = json.dumps({
+                "tenantExtensionTopic": tenant_topic,
+                "message": message
+            })
+            self.producer.produce(self.producer_topic, payload.encode("utf-8"))
+            self.producer.poll(0)
+        except Exception as e:
+            logger.error(f"❌ Error sending message: {e}")
+
+    def consume_messages(self, callback):
+        self.consumer.subscribe([self.consumer_topic])
+        logger.info(f"🎧 Listening to topic '{self.consumer_topic}' as group '{self.group_id}'")
+        try:
+            while True:
+                msg = self.consumer.poll(timeout=1.0)
+                if msg is None:
+                    continue
+                if msg.error():
+                    if msg.error().code() == KafkaError._PARTITION_EOF:
+                        continue
+                    logger.error(msg.error())
+                    continue
+
+                message_obj = {
+                    "queueName": msg.topic(),
+                    "partition": msg.partition(),
+                    "offset": msg.offset(),
+                    "message": msg.value().decode("utf-8"),
+                    "timestamp": msg.timestamp()
+                }
+
+                try:
+                    callback(message_obj)
+                except Exception as cb_err:
+                    logger.error(f"--Consumer error-- {cb_err}")
+
+        except KeyboardInterrupt:
+            logger.info("🛑 Consumer interrupted")
+
+        finally:
+            self.consumer.close()
+            logger.info("🔌 Kafka consumer disconnected")
+    def disconnect(self):
+        self.producer.flush()
+        if self.consumer:
+            self.consumer.close()
+        logger.info("🔌 Kafka connections closed")

py_utils/utils/envs.py

@@ -0,0 +1,102 @@
+"""
+Copyright 2026 CloudScaile
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+
+import os
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field, field_validator, ValidationError
+from typing import Optional
+
+
+
+class Settings(BaseSettings):
+    # Base
+    PORT: int = Field(default=8000, description="Port for the application")
+    PG_DB_REQUIRED: bool = Field(default=False, description="Enable PostgreSQL requirement")
+    KAFKA_REQUIRED: bool = Field(default=False, description="Enable Kafka requirement")
+
+    # PostgreSQL (conditionally required)
+    PG_HOST: Optional[str] = None
+    PG_PORT: Optional[int] = None
+    PG_DB: Optional[str] = None
+    PG_USERNAME: Optional[str] = None
+    PG_PASSWORD: Optional[str] = None
+
+    # Kafka (conditionally required)
+    KAFKA_BROKERS: Optional[str] = None
+    KAFKA_CLIENT_ID: Optional[str] = None
+    KAFKA_GROUP_ID: Optional[str] = Field(default="cs-platform-group-ext")
+    KAFKA_PRODUCER_TOPIC: Optional[str] = Field(default="cs-platform-producer-topic")
+    KAFKA_CONSUMER_TOPIC: Optional[str] = Field(default="cs-platform-consumer-topic")
+    KAFKA_SASL: bool = Field(default=False)
+    KAFKA_SASL_USERNAME: Optional[str] = None
+    KAFKA_SASL_PASSWORD: Optional[str] = None
+
+    # Common required fields
+    TENANT_NAME: str = Field(..., description="Tenant name for the application")
+    EXTENSION_NAME: str = Field(..., description="Name of the extension being configured")
+    PLATFORM_URL: str = Field(..., description="Base URL for the platform API")
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        case_sensitive=True,
+        extra="ignore"  # Ignore unknown env vars like in envalid
+    )
+
+    # --- Convert string "None" to None for all optional fields ---
+    @field_validator(
+        "PG_HOST", "PG_PORT", "PG_DB", "PG_USERNAME", "PG_PASSWORD",
+        "KAFKA_BROKERS", "KAFKA_CLIENT_ID", "KAFKA_GROUP_ID",
+        "KAFKA_PRODUCER_TOPIC", "KAFKA_CONSUMER_TOPIC",
+        "KAFKA_SASL_USERNAME", "KAFKA_SASL_PASSWORD",
+        mode="before"
+    )
+    @classmethod
+    def convert_none_str_to_none(cls, v):
+        if isinstance(v, str) and v.strip().lower() == "none":
+            return None
+        return v
+
+    # --- Conditional Validation ---
+    @field_validator("PG_HOST", "PG_PORT", "PG_DB", "PG_USERNAME", "PG_PASSWORD")
+    @classmethod
+    def require_postgres_if_enabled(cls, v, info):
+        if info.data.get("PG_DB_REQUIRED"):
+            if v in (None, ""):
+                raise ValueError(f"{info.field_name} is required when PG_DB_REQUIRED=True")
+        return v
+
+    @field_validator(
+        "KAFKA_BROKERS", "KAFKA_CLIENT_ID", "KAFKA_GROUP_ID",
+        "KAFKA_PRODUCER_TOPIC", "KAFKA_CONSUMER_TOPIC",
+        "KAFKA_SASL_USERNAME", "KAFKA_SASL_PASSWORD"
+    )
+    @classmethod
+    def require_kafka_if_enabled(cls, v, info):
+        if not info.data.get("KAFKA_REQUIRED"):
+            return v
+
+        if info.field_name in ("KAFKA_SASL_USERNAME", "KAFKA_SASL_PASSWORD"):
+            if info.data.get("KAFKA_SASL") and v in (None, ""):
+                raise ValueError(f"{info.field_name} is required when KAFKA_SASL=True")
+        elif v in (None, ""):
+            raise ValueError(f"{info.field_name} is required when KAFKA_REQUIRED=True")
+
+        return v
+
+
+# Instantiate and export validated settings
+try:
+    envs = Settings()
+    # Replicate JS behavior: inject into os.environ
+    for key, value in envs.model_dump().items():
+        if value is not None:
+            os.environ[key] = str(value)
+except ValidationError as e:
+    print("❌ Environment validation failed:")
+    print(e)
+    raise

py_utils/utils/logger.py

@@ -0,0 +1,22 @@
+"""
+Copyright 2026 CloudScaile
+
+Licensed under the Apache License, Version 2.0
+http://www.apache.org/licenses/LICENSE-2.0
+
+"""
+
+import logging
+
+logger = logging.getLogger("app_logger")
+logger.setLevel(logging.INFO)
+
+handler = logging.StreamHandler()
+
+formatter = logging.Formatter(
+    fmt="%(asctime)s | %(levelname)s | %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S"
+)
+handler.setFormatter(formatter)
+
+logger.addHandler(handler)