In src/runners/quota_scheduler.py around lines 106 to 112, the docstring for the
function that returns the SQL reset statement is missing a Parameters section
for the config parameter; add a Parameters section directly after the short
description and before Returns that documents config: its expected type (e.g., a
config object or module), that it indicates which DB backend to use
(config.sqlite True for SQLite, otherwise PostgreSQL), and any attributes
accessed (e.g., config.sqlite), plus a brief example or note if necessary; keep
wording consistent with other docstrings in the file and match the existing
style.

#!/bin/bash
# Create GitHub issue for missing Parameters section in docstring
gh issue create \
  --repo lightspeed-core/lightspeed-stack \
  --title "Add missing Parameters section to get_reset_quota_statement docstring" \
  --body "## Description

The docstring for the \`get_reset_quota_statement\` function in \`src/runners/quota_scheduler.py\` is missing a Parameters section to document the \`config\` parameter.

For consistency with other docstrings in the file and to fully satisfy documentation standards, a Parameters section should be added.

## Location
- File: \`src/runners/quota_scheduler.py\`
- Function: \`get_reset_quota_statement\`

## References
- Pull Request: https://github.com/lightspeed-core/lightspeed-stack/pull/889
- Review Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/889#discussion_r2602221946
- Requested by: @tisnik" \
  --assignee tisnik

In src/runners/quota_scheduler.py around lines 124 to 138, the docstring's
Parameters section omits the connection parameter; update the docstring to add a
description for connection (e.g., type: DB connection or
Connection/ConnectionLike, purpose: DB connection used to execute the provided
SQL statements) consistent with existing style and wording, placing it alongside
the other parameters and ensuring types and brief purpose are documented.

#!/bin/bash
# Create a GitHub issue for the missing connection parameter documentation

gh issue create \
  --repo lightspeed-core/lightspeed-stack \
  --title "Document connection parameter in quota_revocation docstring" \
  --body "The \`connection\` parameter in the \`quota_revocation\` function (src/runners/quota_scheduler.py) is missing from the docstring's Parameters section.

Related to PR #889 which aims to improve docstrings for the quota scheduler.

**Context:**
- File: \`src/runners/quota_scheduler.py\`
- Function: \`quota_revocation\`
- Issue: The \`connection\` parameter needs to be documented in the Parameters section

**References:**
- PR: https://github.com/lightspeed-core/lightspeed-stack/pull/889
- Comment: https://github.com/lightspeed-core/lightspeed-stack/pull/889#discussion_r2602221964

Requested by: @tisnik" \
  --assignee tisnik

class QuotaLimiterConfiguration(ConfigurationBase):
    """Configuration for one quota limiter.

    There are three configuration options for each limiter:

    1. ``period`` is specified in a human-readable form, see
       https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-INTERVAL-INPUT
       for all possible options. When the end of the period is reached, the
       quota is reset or increased.
    2. ``initial_quota`` is the value set at the beginning of the period.
    3. ``quota_increase`` is the value (if specified) used to increase the
       quota when the period is reached.

    There are two basic use cases:

    1. When the quota needs to be reset to a specific value periodically (for
       example on a weekly or monthly basis), set ``initial_quota`` to the
       required value.
    2. When the quota needs to be increased by a specific value periodically
       (for example on a daily basis), set ``quota_increase``.
    """

    type: Literal["user_limiter", "cluster_limiter"] = Field(
        ...,
        title="Quota limiter type",
        description="Quota limiter type, either user_limiter or cluster_limiter",
    )

    name: str = Field(
        ...,
        title="Quota limiter name",
        description="Human readable quota limiter name",
    )

    initial_quota: NonNegativeInt = Field(
        ...,
        title="Initial quota",
        description="Quota set at beginning of the period",
    )

    quota_increase: NonNegativeInt = Field(
        ...,
        title="Quota increase",
        description="Delta value used to increase quota when period is reached",
    )

    period: str = Field(
        ...,
        title="Period",
        description="Period specified in human readable form",
    )

class QuotaLimiterConfiguration(ConfigurationBase):
    """Configuration for one quota limiter.

    There are three configuration options for each limiter:

    1. ``period`` is specified in a human-readable form, see
       https://www.postgresql.org/docs/current/datatype-datetime.html#DATATYPE-INTERVAL-INPUT
       for all possible options. When the end of the period is reached, the
       quota is reset or increased.
    2. ``initial_quota`` is the value set at the beginning of the period.
    3. ``quota_increase`` is the value (if specified) used to increase quota when the period is reached.

    There are two basic use cases:

    1. When the quota needs to be reset to a specific value periodically (for
       example on a weekly or monthly basis), set ``initial_quota`` to the
       required value.
    2. When the quota needs to be increased by a specific value periodically
       (for example on a daily basis), set ``quota_increase``.
    """

    type: Literal["user_limiter", "cluster_limiter"] = Field(
        ...,
        title="Quota limiter type",
        description="Quota limiter type, either user_limiter or cluster_limiter",
    )

    name: str = Field(
        ...,
        title="Quota limiter name",
        description="Human readable quota limiter name",
    )

    initial_quota: NonNegativeInt = Field(
        ...,
        title="Initial quota",
        description="Quota set at beginning of the period",
    )

    quota_increase: NonNegativeInt = Field(
        ...,
        title="Quota increase",
        description="Delta value used to increase quota when period is reached",
    )

    period: str = Field(
        ...,
        title="Period",
        description="Period specified in human readable form",
    )

def connect_sqlite(config: SQLiteDatabaseConfiguration) -> Any:
    """Initialize connection to database."""
    logger.info("Connecting to SQLite storage")
    # make sure the connection will have known state
    # even if SQLite is not alive
    connection = None
    try:
        connection = sqlite3.connect(database=config.db_path)
        if connection is not None:
            connection.autocommit = True
        return connection
    except sqlite3.Error as e:
        logger.exception("Error initializing SQLite cache:\n%s", e)
        raise

def connect_pg(config: PostgreSQLDatabaseConfiguration) -> Any:
    """Initialize connection to PostgreSQL database."""
    logger.info("Connecting to PostgreSQL storage")
    try:
        connection = psycopg2.connect(
            host=config.host,
            port=config.port,
            user=config.user,
            password=config.password.get_secret_value(),
            dbname=config.db,
            sslmode=config.ssl_mode,
            # sslrootcert=config.ca_cert_path,
            gssencmode=config.gss_encmode,
        )
        if connection is not None:
            connection.autocommit = True
        return connection
    except psycopg2.Error as e:
        logger.exception("Error connecting to PostgreSQL database:\n%s", e)
        raise

def connection(f: Callable) -> Callable:
    """
    Ensure a connectable object is connected before invoking the wrapped function.

    The returned wrapper calls `connectable.connected()` and, if that returns
    `False`, calls `connectable.connect()` prior to delegating to the original
    function.

    Parameters:
        f (Callable): The function to wrap. The wrapped function is
        expected to accept a `connectable` first argument.

    Returns:
        Callable: A wrapper function with signature `(connectable,
        *args, **kwargs)` that ensures `connectable` is connected
        before calling `f`.

    Example:
    ```python
    @connection
    def list_history(self) -> list[str]:
       pass
    ```
    """

    def wrapper(connectable: Any, *args: Any, **kwargs: Any) -> Callable:
        """
        Ensure the provided connectable is connected, then call the wrapped with the same arguments.

        Parameters:
            connectable (Any): Object that implements `connected()` -> bool and
            `connect()` -> None; will be connected if not already.
                *args (Any): Positional arguments forwarded to the wrapped callable.
                **kwargs (Any): Keyword arguments forwarded to the wrapped callable.

        Returns:
                Any: The value returned by the wrapped callable.
        """
        if not connectable.connected():
            connectable.connect()
        return f(connectable, *args, **kwargs)

    return wrapper

class QuotaHandlersConfiguration(ConfigurationBase):
    """Quota limiter configuration.

    It is possible to limit quota usage per user or per service or services
    (that typically run in one cluster). Each limit is configured as a separate
    _quota limiter_. It can be of type `user_limiter` or `cluster_limiter`
    (which is name that makes sense in OpenShift deployment).
    """

    sqlite: Optional[SQLiteDatabaseConfiguration] = Field(
        None,
        title="SQLite configuration",
        description="SQLite database configuration",
    )

    postgres: Optional[PostgreSQLDatabaseConfiguration] = Field(
        None,
        title="PostgreSQL configuration",
        description="PostgreSQL database configuration",
    )

    limiters: list[QuotaLimiterConfiguration] = Field(
        default_factory=list,
        title="Quota limiters",
        description="Quota limiters configuration",
    )

    scheduler: QuotaSchedulerConfiguration = Field(
        default_factory=lambda: QuotaSchedulerConfiguration(period=1),
        title="Quota scheduler",
        description="Quota scheduler configuration",
    )

    enable_token_history: bool = Field(
        False,
        title="Enable token history",
        description="Enables storing information about token usage history",
    )

class Configuration(ConfigurationBase):
    """Global service configuration."""

    name: str = Field(
        ...,
        title="Service name",
        description="Name of the service. That value will be used in REST API endpoints.",
    )

    service: ServiceConfiguration = Field(
        ...,
        title="Service configuration",
        description="This section contains Lightspeed Core Stack service configuration.",
    )

    llama_stack: LlamaStackConfiguration = Field(
        ...,
        title="Llama Stack configuration",
        description="This section contains Llama Stack configuration. "
        "Lightspeed Core Stack service can call Llama Stack in library mode or in server mode.",
    )

    user_data_collection: UserDataCollection = Field(
        ...,
        title="User data collection configuration",
        description="This section contains configuration for subsystem that collects user data"
        "(transcription history and feedbacks).",
    )

    database: DatabaseConfiguration = Field(
        default_factory=lambda: DatabaseConfiguration(sqlite=None, postgres=None),
        title="Database Configuration",
        description="Configuration for database to store conversation IDs and other runtime data",
    )

    mcp_servers: list[ModelContextProtocolServer] = Field(
        default_factory=list,
        title="Model Context Protocol Server and tools configuration",
        description="MCP (Model Context Protocol) servers provide tools and "
        "capabilities to the AI agents. These are configured in this section. "
        "Only MCP servers defined in the lightspeed-stack.yaml configuration are "
        "available to lightspeed-core agents. Tools configured in the llama-stack run.yaml "
        "are not accessible to lightspeed-core agents.",
    )

    authentication: AuthenticationConfiguration = Field(
        default_factory=AuthenticationConfiguration,
        title="Authentication configuration",
        description="Authentication configuration",
    )

    authorization: Optional[AuthorizationConfiguration] = Field(
        None,
        title="Authorization configuration",
        description="Lightspeed Core Stack implements a modular "
        "authentication and authorization system with multiple authentication "
        "methods. Authorization is configurable through role-based access "
        "control. Authentication is handled through selectable modules "
        "configured via the module field in the authentication configuration.",
    )

    customization: Optional[Customization] = Field(
        None,
        title="Custom profile configuration",
        description="It is possible to customize Lightspeed Core Stack via this "
        "section. System prompt can be customized and also different parts of "
        "the service can be replaced by custom Python modules.",
    )

    inference: InferenceConfiguration = Field(
        default_factory=lambda: InferenceConfiguration(
            default_model=None, default_provider=None
        ),
        title="Inference configuration",
        description="One LLM provider and one its model might be selected as "
        "default ones. When no provider+model pair is specified in REST API "
        "calls (query endpoints), the default provider and model are used.",
    )

    conversation_cache: ConversationHistoryConfiguration = Field(
        default_factory=lambda: ConversationHistoryConfiguration(
            type=None, memory=None, sqlite=None, postgres=None
        ),
        title="Conversation history configuration",
        description="Conversation history configuration.",
    )

    byok_rag: list[ByokRag] = Field(
        default_factory=list,
        title="BYOK RAG configuration",
        description="BYOK RAG configuration. This configuration can be used to "
        "reconfigure Llama Stack through its run.yaml configuration file",
    )

    quota_handlers: QuotaHandlersConfiguration = Field(
        default_factory=lambda: QuotaHandlersConfiguration(
            sqlite=None, postgres=None, enable_token_history=False
        ),
        title="Quota handlers",
        description="Quota handlers configuration",
    )

    def dump(self, filename: str = "configuration.json") -> None:
        """
        Write the current Configuration model to a JSON file.

        The configuration is serialized with an indentation of 4 spaces using
        the model's JSON representation and written with UTF-8 encoding. If the
        file exists it will be overwritten.

        Parameters:
            filename (str): Path to the output file (defaults to "configuration.json").
        """
        with open(filename, "w", encoding="utf-8") as fout:
            fout.write(self.model_dump_json(indent=4))