aws-python-helper 0.36.0__tar.gz → 0.38.0__tar.gz

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.36.0
+Version: 0.38.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -38,6 +38,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **Pydantic schema validation**: Declare a `schema` property on any `API` or `Lambda` and the framework validates automatically before `validate()` — returns 400 on failure
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
+- **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -65,6 +66,7 @@ All available classes and functions:
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
+| `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -1164,6 +1166,173 @@ module "my_lambda" {
 
 ---
 
+## 🔍 ModelQueryLambda
+
+`ModelQueryLambda` is a ready-to-use base class for creating MongoDB query-proxy Lambdas. Instead of writing a custom Lambda every time another microservice needs to read data from your MongoDB, you subclass `ModelQueryLambda`, declare an `allowed_collections` whitelist, and the framework exposes both `find` and `aggregate` operations automatically.
+
+**Use case:** microservice A needs to query data owned by microservice B. Microservice B deploys one `model-query` Lambda; microservice A calls it via `LambdaInvoker` passing the collection name and query parameters.
+
+### Creating a model-query Lambda
+
+Create `src/lambda/model-query/main.py` in the microservice that owns the data:
+
+```python
+from aws_python_helper import ModelQueryLambda
+
+class ModelQueryLambda(ModelQueryLambda):
+
+    @property
+    def allowed_collections(self) -> list:
+        return ["orders", "customers"]  # whitelist — unlisted collections are rejected
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+model_query_handler = lambda_handler('model-query')
+
+__all__ = ["model_query_handler"]
+```
+
+### Query modes
+
+#### Aggregate pipeline
+
+Pass a `pipeline` list to run a MongoDB aggregation:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "pipeline": [
+        {"$match": {"status": "pending"}},
+        {"$sort": {"created_at": -1}},
+        {"$limit": 50},
+    ],
+})
+```
+
+#### Find with filter
+
+Pass `filter`, `fields`, `limit`, and/or `skip` to run a `find`:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"customer_id": "abc123", "status": "active"},
+    "fields": {"_id": 1, "total": 1, "status": 1},  # projection
+    "limit": 20,
+    "skip": 0,
+})
+```
+
+**Note:** `pipeline` and `fields` are mutually exclusive — the framework rejects payloads that include both.
+
+#### Querying by `_id`
+
+ObjectId hex strings in `_id` filters are automatically coerced to `ObjectId` so callers can serialize queries as plain JSON:
+
+```python
+# Plain value
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+
+# Operator with list
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": {"$in": ["65f1...", "65f2...", "65f3..."]}},
+})
+
+# 'id' is accepted as an alias for '_id'
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+```
+
+Supported operators on `_id`: scalar (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`) and list (`$in`, `$nin`). The same coercion is applied to `$match` stages inside a `pipeline`. If the string is not a valid 24-char ObjectId hex, the Lambda raises a clear validation error.
+
+### Payload reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session` | `dict` | Yes | Session dict from `self.session.to_dict()` — drives state-scoped DB routing |
+| `collection` | `str` | Yes | Collection name (must be in `allowed_collections`) |
+| `pipeline` | `list` | One of | MongoDB aggregation pipeline |
+| `filter` | `dict` | One of | MongoDB filter document (defaults to `{}`). `_id`/`id` string values are auto-coerced to `ObjectId` |
+| `fields` | `dict` | No | MongoDB projection (only valid with `filter` mode) |
+| `limit` | `int` | No | Max documents to return |
+| `skip` | `int` | No | Documents to skip (default `0`) |
+
+### Response format
+
+The Lambda always returns the standard framework envelope:
+
+```json
+{
+  "success": true,
+  "data": [ ... ]
+}
+```
+
+On validation error (unknown collection, invalid payload):
+
+```json
+{
+  "success": false,
+  "error": "Collection 'unknown' is not allowed. Allowed: orders, customers"
+}
+```
+
+### Calling it from another microservice
+
+```python
+import os
+from aws_python_helper import LambdaInvoker, LambdaInvocationError
+
+class OrdersPostAPI(API):
+
+    async def process(self):
+        try:
+            response = LambdaInvoker().invoke(
+                os.getenv("ORDERS_MODEL_QUERY_LAMBDA_NAME"),
+                payload={
+                    "session": self.session.to_dict(),
+                    "collection": "orders",
+                    "filter": {"status": "pending"},
+                    "limit": 100,
+                },
+            )
+        except LambdaInvocationError as e:
+            self.logger.error(f"model-query invocation failed: {e}")
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        if not response.get("success"):
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        orders = response.get("data", [])
+        self.set_body({"orders": orders})
+```
+
+### Session and database routing
+
+The `session` field in the payload is required. The `ModelQueryLambda` uses `session.state` to resolve the target database — the same state-scoped routing used by all framework components. This means:
+
+- `{"session": {"state": "connecticut"}, ...}` → queries the `connecticut` database
+- `{"session": {"state": "new_jersey"}, ...}` → queries the `new_jersey` database
+
+Always pass `self.session.to_dict()` when calling from an API or Lambda to ensure state propagates correctly.
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/README.md

@@ -18,6 +18,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **Pydantic schema validation**: Declare a `schema` property on any `API` or `Lambda` and the framework validates automatically before `validate()` — returns 400 on failure
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
+- **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -45,6 +46,7 @@ All available classes and functions:
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
+| `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -1144,6 +1146,173 @@ module "my_lambda" {
 
 ---
 
+## 🔍 ModelQueryLambda
+
+`ModelQueryLambda` is a ready-to-use base class for creating MongoDB query-proxy Lambdas. Instead of writing a custom Lambda every time another microservice needs to read data from your MongoDB, you subclass `ModelQueryLambda`, declare an `allowed_collections` whitelist, and the framework exposes both `find` and `aggregate` operations automatically.
+
+**Use case:** microservice A needs to query data owned by microservice B. Microservice B deploys one `model-query` Lambda; microservice A calls it via `LambdaInvoker` passing the collection name and query parameters.
+
+### Creating a model-query Lambda
+
+Create `src/lambda/model-query/main.py` in the microservice that owns the data:
+
+```python
+from aws_python_helper import ModelQueryLambda
+
+class ModelQueryLambda(ModelQueryLambda):
+
+    @property
+    def allowed_collections(self) -> list:
+        return ["orders", "customers"]  # whitelist — unlisted collections are rejected
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+model_query_handler = lambda_handler('model-query')
+
+__all__ = ["model_query_handler"]
+```
+
+### Query modes
+
+#### Aggregate pipeline
+
+Pass a `pipeline` list to run a MongoDB aggregation:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "pipeline": [
+        {"$match": {"status": "pending"}},
+        {"$sort": {"created_at": -1}},
+        {"$limit": 50},
+    ],
+})
+```
+
+#### Find with filter
+
+Pass `filter`, `fields`, `limit`, and/or `skip` to run a `find`:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"customer_id": "abc123", "status": "active"},
+    "fields": {"_id": 1, "total": 1, "status": 1},  # projection
+    "limit": 20,
+    "skip": 0,
+})
+```
+
+**Note:** `pipeline` and `fields` are mutually exclusive — the framework rejects payloads that include both.
+
+#### Querying by `_id`
+
+ObjectId hex strings in `_id` filters are automatically coerced to `ObjectId` so callers can serialize queries as plain JSON:
+
+```python
+# Plain value
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+
+# Operator with list
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": {"$in": ["65f1...", "65f2...", "65f3..."]}},
+})
+
+# 'id' is accepted as an alias for '_id'
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+```
+
+Supported operators on `_id`: scalar (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`) and list (`$in`, `$nin`). The same coercion is applied to `$match` stages inside a `pipeline`. If the string is not a valid 24-char ObjectId hex, the Lambda raises a clear validation error.
+
+### Payload reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session` | `dict` | Yes | Session dict from `self.session.to_dict()` — drives state-scoped DB routing |
+| `collection` | `str` | Yes | Collection name (must be in `allowed_collections`) |
+| `pipeline` | `list` | One of | MongoDB aggregation pipeline |
+| `filter` | `dict` | One of | MongoDB filter document (defaults to `{}`). `_id`/`id` string values are auto-coerced to `ObjectId` |
+| `fields` | `dict` | No | MongoDB projection (only valid with `filter` mode) |
+| `limit` | `int` | No | Max documents to return |
+| `skip` | `int` | No | Documents to skip (default `0`) |
+
+### Response format
+
+The Lambda always returns the standard framework envelope:
+
+```json
+{
+  "success": true,
+  "data": [ ... ]
+}
+```
+
+On validation error (unknown collection, invalid payload):
+
+```json
+{
+  "success": false,
+  "error": "Collection 'unknown' is not allowed. Allowed: orders, customers"
+}
+```
+
+### Calling it from another microservice
+
+```python
+import os
+from aws_python_helper import LambdaInvoker, LambdaInvocationError
+
+class OrdersPostAPI(API):
+
+    async def process(self):
+        try:
+            response = LambdaInvoker().invoke(
+                os.getenv("ORDERS_MODEL_QUERY_LAMBDA_NAME"),
+                payload={
+                    "session": self.session.to_dict(),
+                    "collection": "orders",
+                    "filter": {"status": "pending"},
+                    "limit": 100,
+                },
+            )
+        except LambdaInvocationError as e:
+            self.logger.error(f"model-query invocation failed: {e}")
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        if not response.get("success"):
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        orders = response.get("data", [])
+        self.set_body({"orders": orders})
+```
+
+### Session and database routing
+
+The `session` field in the payload is required. The `ModelQueryLambda` uses `session.state` to resolve the target database — the same state-scoped routing used by all framework components. This means:
+
+- `{"session": {"state": "connecticut"}, ...}` → queries the `connecticut` database
+- `{"session": {"state": "new_jersey"}, ...}` → queries the `new_jersey` database
+
+Always pass `self.session.to_dict()` when calling from an API or Lambda to ensure state propagates correctly.
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/aws_python_helper/__init__.py

@@ -31,6 +31,9 @@ from .repository.base import Repository
 from .context.session import Session, get_session, set_session
 from .context.state_validator import StateValidator, InvalidStateError
 
+# Model Query
+from .model_query import ModelQueryLambda
+
 # Invoker
 from .invoker import (
     LambdaInvoker,
@@ -65,6 +68,7 @@ __all__ = [
     'set_session',
     'StateValidator',
     'InvalidStateError',
+    'ModelQueryLambda',
     'LambdaInvoker',
     'ApiClient',
     'LambdaInvocationError',

aws_python_helper-0.38.0/aws_python_helper/model_query/__init__.py

@@ -0,0 +1,3 @@
+from .base import ModelQueryLambda
+
+__all__ = ["ModelQueryLambda"]

aws_python_helper-0.38.0/aws_python_helper/model_query/base.py

@@ -0,0 +1,179 @@
+"""
+ModelQueryLambda - Generic MongoDB query proxy Lambda for inter-service communication.
+
+Allows other microservices to query any whitelisted collection in this service's
+MongoDB database by invoking this Lambda directly, passing standard MongoDB
+query parameters (filter, pipeline, fields, limit, skip).
+
+Usage — subclass and declare which collections are exposed:
+
+    from aws_python_helper import ModelQueryLambda
+
+    class DocketsModelQueryLambda(ModelQueryLambda):
+        @property
+        def allowed_collections(self) -> list:
+            return ["dockets", "tax_sales"]
+
+Caller payload:
+    {
+        "session": {"state": "connecticut"},
+        "collection": "dockets",
+        "filter":   {"case_type_code": "M10"},   # simple find — option A
+        "pipeline": [...],                        # aggregate — option B (takes precedence)
+        "fields":   {"docket_id": 1, "_id": 0},  # projection (only with filter)
+        "limit":    100,                          # optional
+        "skip":     0                             # optional, default 0
+    }
+
+ObjectId coercion:
+    String values for '_id' (or 'id' as alias) inside `filter` and pipeline
+    `$match` stages are automatically converted to bson.ObjectId. Supports
+    scalar operators ($eq, $ne, $gt, $gte, $lt, $lte) and list operators
+    ($in, $nin). A clear ValueError is raised when the string is not a valid
+    24-char ObjectId hex.
+
+    {"filter": {"_id": "65f1a2b3c4d5e6f7a8b9c0d1"}}
+    {"filter": {"_id": {"$in": ["65f1...", "65f2..."]}}}
+    {"filter": {"id":  "65f1a2b3c4d5e6f7a8b9c0d1"}}  # 'id' is aliased to '_id'
+
+Response (via Lambda base run()):
+    {"success": True, "data": [...]}
+"""
+
+from typing import Any, List, Optional
+from bson import ObjectId
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from ..lambda_standalone.base import Lambda
+
+
+_OBJECT_ID_SCALAR_OPERATORS = {"$eq", "$ne", "$gt", "$gte", "$lt", "$lte"}
+_OBJECT_ID_LIST_OPERATORS = {"$in", "$nin"}
+
+
+def _coerce_object_id(value: Any) -> Any:
+    """Convert a string (or operator dict) to ObjectId where applicable for an '_id' field."""
+    if isinstance(value, ObjectId):
+        return value
+    if isinstance(value, str):
+        if not ObjectId.is_valid(value):
+            raise ValueError(f"'_id' value '{value}' is not a valid ObjectId")
+        return ObjectId(value)
+    if isinstance(value, dict):
+        coerced = {}
+        for op, op_value in value.items():
+            if op in _OBJECT_ID_LIST_OPERATORS:
+                if not isinstance(op_value, list):
+                    raise ValueError(f"'{op}' value for '_id' must be a list")
+                coerced[op] = [_coerce_object_id(v) for v in op_value]
+            elif op in _OBJECT_ID_SCALAR_OPERATORS:
+                coerced[op] = _coerce_object_id(op_value)
+            else:
+                coerced[op] = op_value
+        return coerced
+    raise ValueError(
+        f"Unsupported type for '_id' filter: {type(value).__name__}"
+    )
+
+
+def _normalize_id_key(d: dict) -> None:
+    """Rename 'id' → '_id' (if no _id present) and coerce its value to ObjectId in-place."""
+    if "id" in d and "_id" not in d:
+        d["_id"] = d.pop("id")
+    if "_id" in d:
+        d["_id"] = _coerce_object_id(d["_id"])
+
+
+class _ModelQuerySchema(BaseModel):
+    model_config = ConfigDict(extra="ignore", arbitrary_types_allowed=True)
+
+    collection: str
+    filter: Optional[dict] = None
+    pipeline: Optional[list] = None
+    fields: Optional[dict] = None
+    limit: Optional[int] = None
+    skip: int = 0
+
+    @model_validator(mode="after")
+    def _pipeline_fields_exclusive(self):
+        if self.pipeline is not None and self.fields is not None:
+            raise ValueError("'fields' cannot be used together with 'pipeline'")
+        return self
+
+    @model_validator(mode="after")
+    def _normalize_object_ids(self):
+        if self.filter is not None:
+            _normalize_id_key(self.filter)
+        if self.pipeline is not None:
+            for stage in self.pipeline:
+                if isinstance(stage, dict) and isinstance(stage.get("$match"), dict):
+                    _normalize_id_key(stage["$match"])
+        return self
+
+
+class ModelQueryLambda(Lambda):
+    """
+    Base class for cross-service MongoDB query Lambdas.
+
+    Subclass and override `allowed_collections` to declare which collections
+    this Lambda exposes. Everything else is handled automatically.
+    """
+
+    @property
+    def allowed_collections(self) -> List[str]:
+        """
+        Whitelist of collection names this Lambda is allowed to query.
+
+        Must be overridden — an empty list rejects all requests.
+
+        Example:
+            @property
+            def allowed_collections(self):
+                return ["dockets", "tax_sales"]
+        """
+        return []
+
+    @property
+    def schema(self):
+        return _ModelQuerySchema
+
+    async def validate(self):
+        collection = self.data.get("collection", "")
+
+        if not self.allowed_collections:
+            raise ValueError(
+                "allowed_collections is not configured on this ModelQueryLambda"
+            )
+
+        if collection not in self.allowed_collections:
+            allowed = ", ".join(self.allowed_collections)
+            raise ValueError(
+                f"Collection '{collection}' is not allowed. Allowed: {allowed}"
+            )
+
+    async def process(self) -> Any:
+        collection_name: str = self.data["collection"]
+        database: str = self.data.get("database") or self.session.state
+
+        collection = getattr(getattr(self.db, database), collection_name)
+
+        pipeline: Optional[list] = self.data.get("pipeline")
+
+        if pipeline is not None:
+            results = await collection.aggregate(pipeline).to_list(length=None)
+        else:
+            mongo_filter: dict = self.data.get("filter") or {}
+            fields: Optional[dict] = self.data.get("fields")
+            limit: int = self.data.get("limit") or 0
+            skip: int = self.data.get("skip") or 0
+
+            cursor = collection.find(mongo_filter, fields or {})
+
+            if skip:
+                cursor = cursor.skip(skip)
+            if limit:
+                cursor = cursor.limit(limit)
+
+            results = await cursor.to_list(length=None)
+
+        return results

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/aws_python_helper.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aws-python-helper
-Version: 0.36.0
+Version: 0.38.0
 Summary: AWS Python Helper Framework
 Author-email: Fabian Claros <neufabiae@gmail.com>
 License-Expression: MIT
@@ -38,6 +38,7 @@ Mini-framework to create REST APIs, SQS Consumers, SNS Publishers, Fargate Tasks
 - **Pydantic schema validation**: Declare a `schema` property on any `API` or `Lambda` and the framework validates automatically before `validate()` — returns 400 on failure
 - **LambdaInvoker**: Invoke other Lambda functions (sync or async) with built-in error handling
 - **ApiClient**: HTTP client for inter-service communication — resolves service URLs and auth token from environment variables automatically
+- **ModelQueryLambda**: Base class for MongoDB query-proxy Lambdas — declare an `allowed_collections` whitelist and the framework handles `find` and `aggregate` operations generically
 - **JSON utilities**: Automatic serialization of MongoDB types
 - **Type hints**: Modern Python with type annotations
 - **Async/await**: Full support for asynchronous operations
@@ -65,6 +66,7 @@ All available classes and functions:
 | `FargateExecutor` | `aws_python_helper.fargate.executor` | Launches Fargate tasks from Lambda |
 | `fargate_handler` | `aws_python_helper.fargate.handler` | Entry point handler for Fargate |
 | `Repository` | `aws_python_helper.repository.base` | Base class for MongoDB repositories |
+| `ModelQueryLambda` | `aws_python_helper` | Generic MongoDB query-proxy Lambda base class |
 | `LambdaInvoker` | `aws_python_helper` | Invoke Lambda functions (sync/async) with error handling |
 | `ApiClient` | `aws_python_helper` | HTTP client for inter-service communication |
 | `LambdaInvocationError` | `aws_python_helper` | Raised when boto3 fails to invoke a Lambda |
@@ -1164,6 +1166,173 @@ module "my_lambda" {
 
 ---
 
+## 🔍 ModelQueryLambda
+
+`ModelQueryLambda` is a ready-to-use base class for creating MongoDB query-proxy Lambdas. Instead of writing a custom Lambda every time another microservice needs to read data from your MongoDB, you subclass `ModelQueryLambda`, declare an `allowed_collections` whitelist, and the framework exposes both `find` and `aggregate` operations automatically.
+
+**Use case:** microservice A needs to query data owned by microservice B. Microservice B deploys one `model-query` Lambda; microservice A calls it via `LambdaInvoker` passing the collection name and query parameters.
+
+### Creating a model-query Lambda
+
+Create `src/lambda/model-query/main.py` in the microservice that owns the data:
+
+```python
+from aws_python_helper import ModelQueryLambda
+
+class ModelQueryLambda(ModelQueryLambda):
+
+    @property
+    def allowed_collections(self) -> list:
+        return ["orders", "customers"]  # whitelist — unlisted collections are rejected
+```
+
+Register the handler in `src/handlers/lambda_handler.py`:
+
+```python
+from aws_python_helper.lambda_standalone.handler import lambda_handler
+
+model_query_handler = lambda_handler('model-query')
+
+__all__ = ["model_query_handler"]
+```
+
+### Query modes
+
+#### Aggregate pipeline
+
+Pass a `pipeline` list to run a MongoDB aggregation:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "pipeline": [
+        {"$match": {"status": "pending"}},
+        {"$sort": {"created_at": -1}},
+        {"$limit": 50},
+    ],
+})
+```
+
+#### Find with filter
+
+Pass `filter`, `fields`, `limit`, and/or `skip` to run a `find`:
+
+```python
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"customer_id": "abc123", "status": "active"},
+    "fields": {"_id": 1, "total": 1, "status": 1},  # projection
+    "limit": 20,
+    "skip": 0,
+})
+```
+
+**Note:** `pipeline` and `fields` are mutually exclusive — the framework rejects payloads that include both.
+
+#### Querying by `_id`
+
+ObjectId hex strings in `_id` filters are automatically coerced to `ObjectId` so callers can serialize queries as plain JSON:
+
+```python
+# Plain value
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+
+# Operator with list
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"_id": {"$in": ["65f1...", "65f2...", "65f3..."]}},
+})
+
+# 'id' is accepted as an alias for '_id'
+invoker.invoke("ServiceModelQuery-dev", payload={
+    "session": self.session.to_dict(),
+    "collection": "orders",
+    "filter": {"id": "65f1a2b3c4d5e6f7a8b9c0d1"},
+})
+```
+
+Supported operators on `_id`: scalar (`$eq`, `$ne`, `$gt`, `$gte`, `$lt`, `$lte`) and list (`$in`, `$nin`). The same coercion is applied to `$match` stages inside a `pipeline`. If the string is not a valid 24-char ObjectId hex, the Lambda raises a clear validation error.
+
+### Payload reference
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `session` | `dict` | Yes | Session dict from `self.session.to_dict()` — drives state-scoped DB routing |
+| `collection` | `str` | Yes | Collection name (must be in `allowed_collections`) |
+| `pipeline` | `list` | One of | MongoDB aggregation pipeline |
+| `filter` | `dict` | One of | MongoDB filter document (defaults to `{}`). `_id`/`id` string values are auto-coerced to `ObjectId` |
+| `fields` | `dict` | No | MongoDB projection (only valid with `filter` mode) |
+| `limit` | `int` | No | Max documents to return |
+| `skip` | `int` | No | Documents to skip (default `0`) |
+
+### Response format
+
+The Lambda always returns the standard framework envelope:
+
+```json
+{
+  "success": true,
+  "data": [ ... ]
+}
+```
+
+On validation error (unknown collection, invalid payload):
+
+```json
+{
+  "success": false,
+  "error": "Collection 'unknown' is not allowed. Allowed: orders, customers"
+}
+```
+
+### Calling it from another microservice
+
+```python
+import os
+from aws_python_helper import LambdaInvoker, LambdaInvocationError
+
+class OrdersPostAPI(API):
+
+    async def process(self):
+        try:
+            response = LambdaInvoker().invoke(
+                os.getenv("ORDERS_MODEL_QUERY_LAMBDA_NAME"),
+                payload={
+                    "session": self.session.to_dict(),
+                    "collection": "orders",
+                    "filter": {"status": "pending"},
+                    "limit": 100,
+                },
+            )
+        except LambdaInvocationError as e:
+            self.logger.error(f"model-query invocation failed: {e}")
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        if not response.get("success"):
+            raise ValueError("Could not retrieve orders. Please try again later.")
+
+        orders = response.get("data", [])
+        self.set_body({"orders": orders})
+```
+
+### Session and database routing
+
+The `session` field in the payload is required. The `ModelQueryLambda` uses `session.state` to resolve the target database — the same state-scoped routing used by all framework components. This means:
+
+- `{"session": {"state": "connecticut"}, ...}` → queries the `connecticut` database
+- `{"session": {"state": "new_jersey"}, ...}` → queries the `new_jersey` database
+
+Always pass `self.session.to_dict()` when calling from an API or Lambda to ensure state propagates correctly.
+
+---
+
 ## 🏗️ Architecture Overview
 
 Typical flow for event-driven architectures using this framework:

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/aws_python_helper.egg-info/SOURCES.txt

@@ -35,6 +35,8 @@ aws_python_helper/lambda_standalone/__init__.py
 aws_python_helper/lambda_standalone/base.py
 aws_python_helper/lambda_standalone/fetcher.py
 aws_python_helper/lambda_standalone/handler.py
+aws_python_helper/model_query/__init__.py
+aws_python_helper/model_query/base.py
 aws_python_helper/repository/__init__.py
 aws_python_helper/repository/base.py
 aws_python_helper/sns/__init__.py

{aws_python_helper-0.36.0 → aws_python_helper-0.38.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "aws-python-helper"
-version = "0.36.0"
+version = "0.38.0"
 description = "AWS Python Helper Framework"
 readme = "README.md"
 requires-python = ">=3.9"