groundwork-method 0.0.1 → 0.11.0

package/src/generators/python-microservice/files/src/__packageName__/adapters/message_queue.py.template

@@ -0,0 +1,29 @@
+import json
+<% if (messaging === 'redis') { %>
+import redis.asyncio as redis
+from <%= packageName %>.adapters.config import settings
+
+class RedisMessageQueue:
+    def __init__(self):
+        self.redis = redis.from_url(settings.redis_url)
+        
+    async def publish(self, topic: str, payload: dict) -> None:
+        await self.redis.publish(topic, json.dumps(payload))
+        
+    async def close(self):
+        await self.redis.close()
+<% } %>
+
+<% if (messaging === 'kafka') { %>
+# Kafka implementation would go here using aiokafka
+class KafkaMessageQueue:
+    async def publish(self, topic: str, payload: dict) -> None:
+        pass
+<% } %>
+
+<% if (messaging === 'gcp-pubsub') { %>
+# GCP PubSub implementation would go here using google-cloud-pubsub
+class GCPMessageQueue:
+    async def publish(self, topic: str, payload: dict) -> None:
+        pass
+<% } %>

package/src/generators/python-microservice/files/src/__packageName__/adapters/repository.py.template

@@ -0,0 +1,130 @@
+import base64
+import json
+import datetime
+from typing import Optional, Tuple
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select, func
+from sqlalchemy.dialects.postgresql import insert
+from sqlalchemy.orm import Mapped, mapped_column
+from <%= packageName %>.core.domain.entities import ExampleEntity, PaginatedResult, IdempotencyResponse
+from <%= packageName %>.adapters.database import Base
+
+# SQLAlchemy Models
+class ExampleModel(Base):
+    __tablename__ = "examples"
+    
+    id: Mapped[str] = mapped_column(primary_key=True)
+    name: Mapped[str]
+    description: Mapped[Optional[str]]
+    
+    def to_domain(self) -> ExampleEntity:
+        return ExampleEntity(id=self.id, name=self.name, description=self.description)
+        
+    @classmethod
+    def from_domain(cls, entity: ExampleEntity) -> "ExampleModel":
+        return cls(id=entity.id, name=entity.name, description=entity.description)
+
+class IdempotencyKeyModel(Base):
+    __tablename__ = "idempotency_keys"
+    
+    key: Mapped[str] = mapped_column(primary_key=True)
+    user_id: Mapped[str]
+    status: Mapped[str]
+    response_code: Mapped[Optional[int]]
+    response_body: Mapped[Optional[str]]
+    response_headers: Mapped[Optional[str]]
+    created_at: Mapped[datetime.datetime] = mapped_column(server_default=func.now())
+    updated_at: Mapped[datetime.datetime] = mapped_column(server_default=func.now(), onupdate=func.now())
+
+# Repository Implementation
+class PostgresExampleRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+        
+    async def get_by_id(self, entity_id: str) -> Optional[ExampleEntity]:
+        result = await self.session.execute(
+            select(ExampleModel).where(ExampleModel.id == entity_id)
+        )
+        model = result.scalar_one_or_none()
+        return model.to_domain() if model else None
+        
+    async def save(self, entity: ExampleEntity) -> None:
+        model = ExampleModel.from_domain(entity)
+        self.session.add(model)
+        await self.session.commit()
+        
+    async def list_items(self, limit: int = 10, cursor: Optional[str] = None) -> PaginatedResult[ExampleEntity]:
+        query = select(ExampleModel).order_by(ExampleModel.id.asc()).limit(limit + 1)
+        
+        if cursor:
+            try:
+                decoded_cursor = base64.b64decode(cursor).decode('utf-8')
+                query = query.where(ExampleModel.id > decoded_cursor)
+            except Exception:
+                pass # Invalid cursor handled gracefully
+                
+        result = await self.session.execute(query)
+        models = result.scalars().all()
+        
+        has_more = len(models) > limit
+        items = models[:limit]
+        
+        next_cursor = None
+        if has_more and items:
+            last_id = items[-1].id
+            next_cursor = base64.b64encode(last_id.encode('utf-8')).decode('utf-8')
+            
+        domain_items = [model.to_domain() for model in items]
+        return PaginatedResult(items=domain_items, next_cursor=next_cursor, has_more=has_more)
+
+class PostgresIdempotencyRepository:
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+    async def get(self, key: str, user_id: str) -> Optional[Tuple[str, Optional[IdempotencyResponse]]]:
+        result = await self.session.execute(
+            select(IdempotencyKeyModel).where(
+                IdempotencyKeyModel.key == key,
+                IdempotencyKeyModel.user_id == user_id
+            )
+        )
+        model = result.scalar_one_or_none()
+        if not model:
+            return None
+            
+        if model.status == "COMPLETED" and model.response_code is not None:
+            headers = json.loads(model.response_headers) if model.response_headers else {}
+            resp = IdempotencyResponse(
+                status_code=model.response_code,
+                headers=headers,
+                body=model.response_body or ""
+            )
+            return (model.status, resp)
+            
+        return (model.status, None)
+
+    async def lock(self, key: str, user_id: str) -> bool:
+        # Atomic insert: if the key exists, do nothing (fails to acquire lock)
+        stmt = insert(IdempotencyKeyModel).values(
+            key=key,
+            user_id=user_id,
+            status="IN_PROGRESS"
+        ).on_conflict_do_nothing()
+        
+        result = await self.session.execute(stmt)
+        await self.session.commit()
+        return result.rowcount > 0
+
+    async def save(self, key: str, user_id: str, response: IdempotencyResponse) -> None:
+        result = await self.session.execute(
+            select(IdempotencyKeyModel).where(
+                IdempotencyKeyModel.key == key,
+                IdempotencyKeyModel.user_id == user_id
+            )
+        )
+        model = result.scalar_one()
+        model.status = "COMPLETED"
+        model.response_code = response.status_code
+        model.response_body = response.body
+        model.response_headers = json.dumps(response.headers)
+        await self.session.commit()

package/src/generators/python-microservice/files/src/__packageName__/adapters/telemetry.py.template

@@ -0,0 +1,68 @@
+"""OpenTelemetry bootstrap for the FastAPI app.
+
+Builds a TracerProvider with an OTLP gRPC exporter and instruments the FastAPI
+app so inbound requests produce spans that are exported to the configured
+collector (Jaeger in dev). Mirrors the Go scaffold: BatchSpanProcessor +
+ParentBased(AlwaysSample) default sampler, service.name set on the resource.
+
+Also configures structured JSON logging with trace_id/span_id correlation so
+logs are joinable to traces.
+"""
+import logging
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter
+from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.semconv.resource import ResourceAttributes
+from pythonjsonlogger import jsonlogger
+
+
+def setup_telemetry(app, endpoint: str) -> TracerProvider:
+    """Initialize tracing and instrument the FastAPI app.
+
+    Returns the TracerProvider so the caller can shut it down (flush the
+    BatchSpanProcessor) on application stop.
+    """
+    resource = Resource.create({ResourceAttributes.SERVICE_NAME: "<%= name %>"})
+
+    provider = TracerProvider(resource=resource)
+    # insecure=True: the dev endpoint is plain h2c (http://...:4317), no TLS.
+    exporter = OTLPSpanExporter(endpoint=endpoint, insecure=True)
+    provider.add_span_processor(BatchSpanProcessor(exporter))
+
+    trace.set_tracer_provider(provider)
+    FastAPIInstrumentor.instrument_app(app)
+    return provider
+
+
+class _TraceContextFilter(logging.Filter):
+    """Attaches the active span's trace_id/span_id to every log record."""
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        span = trace.get_current_span()
+        ctx = span.get_span_context()
+        if ctx.is_valid:
+            record.trace_id = format(ctx.trace_id, "032x")
+            record.span_id = format(ctx.span_id, "016x")
+        else:
+            record.trace_id = ""
+            record.span_id = ""
+        return True
+
+
+def setup_logging() -> None:
+    """Configure root logging as JSON with trace correlation fields."""
+    handler = logging.StreamHandler()
+    handler.setFormatter(
+        jsonlogger.JsonFormatter(
+            "%(asctime)s %(levelname)s %(name)s %(message)s %(trace_id)s %(span_id)s"
+        )
+    )
+    handler.addFilter(_TraceContextFilter())
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)

package/src/generators/python-microservice/files/src/__packageName__/adapters/websocket_hub.py.template

@@ -0,0 +1,36 @@
+import json
+import redis.asyncio as redis
+from <%= packageName %>.adapters.config import settings
+import asyncio
+from typing import Set
+
+class WebSocketHub:
+    def __init__(self):
+        self.redis = redis.from_url(settings.redis_url)
+        self.pubsub = self.redis.pubsub()
+        self.active_connections: Set = set()
+        self.background_tasks: Set[asyncio.Task] = set()
+        
+    async def connect(self, websocket):
+        await websocket.accept()
+        self.active_connections.add(websocket)
+        
+    def disconnect(self, websocket):
+        self.active_connections.discard(websocket)
+        
+    async def subscribe(self, channel: str):
+        await self.pubsub.subscribe(channel)
+        
+        task = asyncio.create_task(self._listen())
+        self.background_tasks.add(task)
+        task.add_done_callback(self.background_tasks.discard)
+        
+    async def _listen(self):
+        async for message in self.pubsub.listen():
+            if message['type'] == 'message':
+                data = message['data'].decode('utf-8')
+                for connection in self.active_connections:
+                    await connection.send_text(data)
+                    
+    async def broadcast(self, channel: str, message: dict):
+        await self.redis.publish(channel, json.dumps(message))

package/src/generators/python-microservice/files/src/__packageName__/core/domain/entities.py.template

@@ -0,0 +1,22 @@
+from typing import Generic, TypeVar, List, Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+T = TypeVar("T")
+
+class PaginatedResult(BaseModel, Generic[T]):
+    """Generic cursor-based pagination result."""
+    items: List[T]
+    next_cursor: Optional[str] = None
+    has_more: bool = False
+
+class IdempotencyResponse(BaseModel):
+    """Domain representation of a cached HTTP response."""
+    status_code: int
+    headers: Dict[str, str]
+    body: str
+
+class ExampleEntity(BaseModel):
+    """An example entity for the service."""
+    id: str
+    name: str
+    description: Optional[str] = None

package/src/generators/python-microservice/files/src/__packageName__/core/domain/exceptions.py.template

@@ -0,0 +1,43 @@
+class DomainError(Exception):
+    """Base class for domain exceptions."""
+    pass
+
+class NotFoundError(DomainError):
+    """Raised when a requested resource is not found."""
+    pass
+
+class UnauthorizedError(DomainError):
+    """Raised when authentication is missing or invalid."""
+    pass
+
+class ForbiddenError(DomainError):
+    """Raised when the user does not have permission."""
+    pass
+
+class ConflictError(DomainError):
+    """Raised when there is a conflict, such as a duplicate resource."""
+    pass
+
+class ValidationError(DomainError):
+    """Raised for field-level validation errors."""
+    pass
+
+class IdempotencyError(DomainError):
+    """Raised when an idempotency key collision occurs."""
+    pass
+
+class RateLimitExceededError(DomainError):
+    """Raised when concurrency limits or rate limits are exceeded."""
+    pass
+
+class CircuitBreakerOpenError(DomainError):
+    """Raised when an external service circuit breaker is open."""
+    pass
+
+class TransientInferenceError(DomainError):
+    """Raised for retriable provider/ML failures."""
+    pass
+
+class PermanentInferenceError(DomainError):
+    """Raised for non-retriable provider/ML failures."""
+    pass

package/src/generators/python-microservice/files/src/__packageName__/core/ports.py.template

@@ -0,0 +1,42 @@
+from typing import Protocol, Optional, Tuple
+from <%= packageName %>.core.domain.entities import ExampleEntity, PaginatedResult, IdempotencyResponse
+
+class IdempotencyRepository(Protocol):
+    """Port for storing idempotency state."""
+    
+    async def get(self, key: str, user_id: str) -> Optional[Tuple[str, Optional[IdempotencyResponse]]]:
+        """Returns (status, cached_response) if key exists, else None."""
+        ...
+        
+    async def lock(self, key: str, user_id: str) -> bool:
+        """Attempts to acquire lock (IN_PROGRESS). Returns True if successful."""
+        ...
+        
+    async def save(self, key: str, user_id: str, response: IdempotencyResponse) -> None:
+        """Saves completed response and marks as COMPLETED."""
+        ...
+
+<% if (postgres) { %>
+class ExampleRepository(Protocol):
+    """Port for ExampleEntity storage."""
+    
+    async def get_by_id(self, entity_id: str) -> Optional[ExampleEntity]:
+        ...
+        
+    async def save(self, entity: ExampleEntity) -> None:
+        ...
+        
+    async def list_items(self, limit: int = 10, cursor: Optional[str] = None) -> PaginatedResult[ExampleEntity]:
+        ...
+<% } %>
+
+<% if (messaging !== 'none') { %>
+class MessageQueue(Protocol):
+    """Port for publishing events."""
+    
+    async def publish(self, topic: str, payload: dict) -> None:
+        ...
+<% } %>
+<%# The TextGenerator port lives in the package's core/llm.py, generated by the
+    llm capability (plan WS-F), so the same port is reusable by the standalone
+    add-capability generator on existing services. %>

package/src/generators/python-microservice/files/src/__packageName__/core/service/example_service.py.template

@@ -0,0 +1,68 @@
+from <%= packageName %>.core.domain.entities import ExampleEntity, PaginatedResult
+from <%= packageName %>.core.domain.exceptions import NotFoundError
+<% if (postgres) { %>
+from <%= packageName %>.core.ports import ExampleRepository
+<% } %>
+<% if (messaging !== 'none') { %>
+from <%= packageName %>.core.ports import MessageQueue
+<% } %>
+<% if (llm) { %>
+from <%= packageName %>.core.llm import TextGenerator
+<% } %>
+import uuid
+
+class ExampleService:
+    def __init__(
+        self,
+<% if (postgres) { %>
+        repository: ExampleRepository,
+<% } %>
+<% if (messaging !== 'none') { %>
+        message_queue: MessageQueue,
+<% } %>
+<% if (llm) { %>
+        text_generator: TextGenerator,
+<% } %>
+    ):
+<% if (postgres) { %>
+        self.repository = repository
+<% } %>
+<% if (messaging !== 'none') { %>
+        self.message_queue = message_queue
+<% } %>
+<% if (llm) { %>
+        self.text_generator = text_generator
+<% } %>
+<% if (!postgres && messaging === 'none' && !llm) { %>
+        pass
+<% } %>
+
+    async def create_example(self, name: str) -> ExampleEntity:
+        entity = ExampleEntity(id=str(uuid.uuid4()), name=name)
+        
+<% if (llm) { %>
+        # Generate description using LLM
+        description = await self.text_generator.generate_text(f"Describe a thing named {name}")
+        entity.description = description
+<% } %>
+
+<% if (postgres) { %>
+        await self.repository.save(entity)
+<% } %>
+
+<% if (messaging !== 'none') { %>
+        await self.message_queue.publish("example.created", entity.model_dump())
+<% } %>
+
+        return entity
+
+<% if (postgres) { %>
+    async def get_example(self, entity_id: str) -> ExampleEntity:
+        entity = await self.repository.get_by_id(entity_id)
+        if not entity:
+            raise NotFoundError(f"Example {entity_id} not found")
+        return entity
+        
+    async def list_examples(self, limit: int = 10, cursor: str | None = None) -> PaginatedResult[ExampleEntity]:
+        return await self.repository.list_items(limit, cursor)
+<% } %>

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/api/dependencies.py.template

@@ -0,0 +1,50 @@
+from fastapi import Depends
+from <%= packageName %>.core.service.example_service import ExampleService
+
+<% if (postgres) { %>
+from sqlalchemy.ext.asyncio import AsyncSession
+from <%= packageName %>.core.ports import ExampleRepository
+from <%= packageName %>.adapters.database import get_db_session
+from <%= packageName %>.adapters.repository import PostgresExampleRepository
+
+def get_example_repository(session: AsyncSession = Depends(get_db_session)) -> ExampleRepository:
+    return PostgresExampleRepository(session)
+<% } %>
+
+<% if (messaging !== 'none') { %>
+from <%= packageName %>.core.ports import MessageQueue
+from <%= packageName %>.adapters.message_queue import <% if (messaging === 'redis') { %>RedisMessageQueue<% } else if (messaging === 'kafka') { %>KafkaMessageQueue<% } else { %>GCPMessageQueue<% } %>
+def get_message_queue() -> MessageQueue:
+    # In a real app this might be a singleton in app state, but for scaffold we instantiate
+    return <% if (messaging === 'redis') { %>RedisMessageQueue()<% } else if (messaging === 'kafka') { %>KafkaMessageQueue()<% } else { %>GCPMessageQueue()<% } %>
+<% } %>
+
+<% if (llm) { %>
+from <%= packageName %>.core.llm import TextGenerator
+from <%= packageName %>.adapters.llm import LLMClient
+def get_text_generator() -> TextGenerator:
+    return LLMClient()
+<% } %>
+
+def get_example_service(
+<% if (postgres) { %>
+    repository: ExampleRepository = Depends(get_example_repository),
+<% } %>
+<% if (messaging !== 'none') { %>
+    message_queue: MessageQueue = Depends(get_message_queue),
+<% } %>
+<% if (llm) { %>
+    text_generator: TextGenerator = Depends(get_text_generator),
+<% } %>
+) -> ExampleService:
+    return ExampleService(
+<% if (postgres) { %>
+        repository=repository,
+<% } %>
+<% if (messaging !== 'none') { %>
+        message_queue=message_queue,
+<% } %>
+<% if (llm) { %>
+        text_generator=text_generator,
+<% } %>
+    )

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/api/middleware.py.template

@@ -0,0 +1,131 @@
+import json
+import asyncio
+from typing import Optional
+from fastapi import Request, status
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from <%= packageName %>.core.domain.exceptions import (
+    NotFoundError,
+    ConflictError,
+    ValidationError,
+    IdempotencyError,
+    RateLimitExceededError,
+    CircuitBreakerOpenError,
+    TransientInferenceError
+)
+from <%= packageName %>.core.ports import IdempotencyRepository
+from <%= packageName %>.core.domain.entities import IdempotencyResponse
+from <%= packageName %>.adapters.config import settings
+
+class DomainExceptionHandlerMiddleware(BaseHTTPMiddleware):
+    """Maps domain exceptions to appropriate HTTP responses."""
+    async def dispatch(self, request: Request, call_next):
+        try:
+            return await call_next(request)
+        except NotFoundError as e:
+            return JSONResponse(status_code=status.HTTP_404_NOT_FOUND, content={"detail": str(e)})
+        except (ConflictError, IdempotencyError) as e:
+            return JSONResponse(status_code=status.HTTP_409_CONFLICT, content={"detail": str(e)})
+        except ValidationError as e:
+            return JSONResponse(status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, content={"detail": str(e)})
+        except RateLimitExceededError as e:
+            return JSONResponse(status_code=status.HTTP_429_TOO_MANY_REQUESTS, content={"detail": str(e)})
+        except (TransientInferenceError, CircuitBreakerOpenError) as e:
+            return JSONResponse(status_code=status.HTTP_503_SERVICE_UNAVAILABLE, content={"detail": str(e)})
+        except Exception as e:
+            # Let unhandled exceptions propagate or log them here
+            raise e
+
+class GlobalTimeoutMiddleware(BaseHTTPMiddleware):
+    """Ensures requests do not hang indefinitely."""
+    def __init__(self, app, timeout: float = 30.0):
+        super().__init__(app)
+        self.timeout = timeout
+
+    async def dispatch(self, request: Request, call_next):
+        try:
+            return await asyncio.wait_for(call_next(request), timeout=self.timeout)
+        except asyncio.TimeoutError:
+            return JSONResponse(
+                status_code=status.HTTP_504_GATEWAY_TIMEOUT,
+                content={"detail": "Request execution timed out."}
+            )
+
+class ConcurrencyLimitingMiddleware(BaseHTTPMiddleware):
+    """Load shedder utilizing a semaphore to limit concurrent requests."""
+    def __init__(self, app, max_concurrent_requests: int):
+        super().__init__(app)
+        self.semaphore = asyncio.Semaphore(max_concurrent_requests)
+
+    async def dispatch(self, request: Request, call_next):
+        if self.semaphore.locked():
+            return JSONResponse(
+                status_code=status.HTTP_503_SERVICE_UNAVAILABLE,
+                content={"detail": "Service overloaded. Please try again later."}
+            )
+        async with self.semaphore:
+            return await call_next(request)
+
+class IdempotencyMiddleware(BaseHTTPMiddleware):
+    """
+    Ensures mutating requests (POST/PUT/PATCH/DELETE) with an Idempotency-Key 
+    are only executed once. Uses injected IdempotencyRepository from app state.
+    """
+    async def dispatch(self, request: Request, call_next):
+        if request.method in ["GET", "OPTIONS", "HEAD"]:
+            return await call_next(request)
+            
+        idem_key = request.headers.get("Idempotency-Key")
+        if not idem_key:
+            return await call_next(request)
+            
+        # In real life, extract user_id from auth token
+        user_id = "anonymous"
+        
+        # We need the repository. Ideally injected into app state during lifespan.
+        repo: Optional[IdempotencyRepository] = getattr(request.app.state, "idempotency_repo", None)
+        if not repo:
+            # If repo isn't configured, degrade gracefully or fail. 
+            return await call_next(request)
+
+        # 1. Check if already executed
+        result = await repo.get(idem_key, user_id)
+        if result:
+            state, cached_response = result
+            if state == "IN_PROGRESS":
+                return JSONResponse(
+                    status_code=status.HTTP_409_CONFLICT,
+                    content={"detail": "Request with this Idempotency-Key is already in progress."}
+                )
+            if state == "COMPLETED" and cached_response:
+                return JSONResponse(
+                    status_code=cached_response.status_code,
+                    content=json.loads(cached_response.body) if cached_response.body else None,
+                    headers=cached_response.headers
+                )
+
+        # 2. Acquire lock
+        acquired = await repo.lock(idem_key, user_id)
+        if not acquired:
+            return JSONResponse(
+                status_code=status.HTTP_409_CONFLICT,
+                content={"detail": "Concurrent request with this Idempotency-Key detected."}
+            )
+            
+        # 3. Execute
+        response = await call_next(request)
+        
+        # 4. Cache successful responses (2xx)
+        if 200 <= response.status_code < 300:
+            # To cache the body, we have to extract it, which is complex in ASGI.
+            # For simplicity in this scaffold, we store a basic body or use custom routers.
+            # Real robust implementation should buffer the ASGI chunks.
+            # We'll just cache the status here for demonstration.
+            resp_to_cache = IdempotencyResponse(
+                status_code=response.status_code,
+                headers=dict(response.headers),
+                body='{"status": "completed"}' # Mocked for middleware.
+            )
+            await repo.save(idem_key, user_id, resp_to_cache)
+            
+        return response

package/src/generators/python-microservice/files/src/__packageName__/entrypoints/api/router.py.template

@@ -0,0 +1,37 @@
+from fastapi import APIRouter, Depends, Query
+from pydantic import BaseModel
+from typing import Optional
+from <%= packageName %>.core.service.example_service import ExampleService
+from <%= packageName %>.entrypoints.api.dependencies import get_example_service
+
+router = APIRouter(prefix="/examples", tags=["examples"])
+
+class CreateExampleRequest(BaseModel):
+    name: str
+
+@router.post("")
+async def create_example(
+    request: CreateExampleRequest,
+    service: ExampleService = Depends(get_example_service)
+):
+    entity = await service.create_example(name=request.name)
+    return entity
+
+<% if (postgres) { %>
+@router.get("/{entity_id}")
+async def get_example(
+    entity_id: str,
+    service: ExampleService = Depends(get_example_service)
+):
+    entity = await service.get_example(entity_id)
+    return entity
+
+@router.get("")
+async def list_examples(
+    limit: int = Query(10, ge=1, le=100),
+    cursor: Optional[str] = None,
+    service: ExampleService = Depends(get_example_service)
+):
+    result = await service.list_examples(limit=limit, cursor=cursor)
+    return result
+<% } %>