celerp 1.2.0__tar.gz → 1.2.4__tar.gz

{celerp-1.2.0 → celerp-1.2.4}/CONTRIBUTING.md

@@ -14,7 +14,7 @@ follows:
   commercial terms). Open an issue before substantial work and we will arrange signing.
 - **Third-party modules you do not submit upstream** (e.g. your own marketplace modules) need no CLA - a
   Developer Certificate of Origin sign-off (`git commit -s`) is sufficient for those. The MIT modules are
-  the recommended starting point: fork one, rename it (see `TRADEMARK.md`), and license your derivative
+  the recommended starting point: fork one, rename it (see `legal/TRADEMARK.md`), and license your derivative
   however you wish.
 
 **How CLA acceptance works.** Contributions to official Celerp repositories require CLA acceptance before
@@ -23,7 +23,7 @@ pull request, post the exact acceptance phrase from your authenticated GitHub ac
 acceptance is recorded against the current `CLA.md` version. The bot blocks merge until acceptance is
 recorded.
 
-Trademarks are not licensed by any code license; see `TRADEMARK.md`.
+Trademarks are not licensed by any code license; see `legal/TRADEMARK.md`.
 
 ## Environment variables
 

celerp-1.2.4/LICENSE

@@ -0,0 +1,107 @@
+Business Source License 1.1
+
+License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+"Business Source License" is a trademark of MariaDB Corporation Ab.
+
+-----------------------------------------------------------------------------
+
+Parameters
+
+Licensor:             Noah Severs
+Licensed Work:        Celerp
+                      The Licensed Work is (c) 2026 Noah Severs
+Additional Use Grant: You may use the Licensed Work in production to operate
+                      Celerp for your own internal business purposes, including
+                      self-hosted use by your company and its affiliates. This
+                      Additional Use Grant does not include offering the Licensed
+                      Work, modified versions of the Licensed Work, or a
+                      substantially similar competing product as a hosted service,
+                      SaaS service, managed service, OEM product, or white-label
+                      product to third parties without a commercial agreement with
+                      Licensor.
+
+Change Date:          2029-01-01
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work
+(including commercial licensing, OEM agreements, and white-label inquiries),
+please contact https://celerp.com.
+
+-----------------------------------------------------------------------------
+
+Notice
+
+The Business Source License (this document, or the "License") is not an Open
+Source license. However, the Licensed Work will eventually be made available
+under an Open Source License, as stated in this License.
+
+-----------------------------------------------------------------------------
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited production
+use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of
+the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or modified
+form from a third party, the terms and conditions set forth in this License
+apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor
+or its affiliates (provided that you may use a trademark or logo of Licensor
+as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
+"AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
+OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+MariaDB hereby grants you permission to use this License's text to license
+your works, and to refer to it using the trademark "Business Source License",
+as long as you comply with the Covenants of Licensor below.
+
+-----------------------------------------------------------------------------
+
+Covenants of Licensor
+
+In consideration of the right to use this License's text and the "Business
+Source License" name and trademark, Licensor covenants to MariaDB, and to all
+other recipients of the licensed work to be provided by Licensor:
+
+1. To specify as the Change License the GPL Version 2.0 or any later version,
+   or a license that is compatible with GPL Version 2.0 or a later version,
+   where "compatible" means that software provided under the Change License can
+   be included in a program with software provided under GPL Version 2.0 or a
+   later version. Licensor may specify additional Change Licenses without
+   limitation.
+
+2. To either: (a) specify an additional grant of rights to use that does not
+   impose any additional restriction on the right granted in this License, as
+   the Additional Use Grant; or (b) insert the text "None".
+
+3. To specify a Change Date.
+
+4. Not to modify this License in any other way.

{celerp-1.2.0 → celerp-1.2.4}/LICENSING.md

@@ -7,11 +7,11 @@ operative statement for that file; this map governs by path otherwise.
 | Path | License | Text |
 |---|---|---|
 | `celerp/` (engine/kernel) | Business Source License 1.1 | `LICENSE` |
-| `celerp/gateway/`, `celerp/session_gate.py`, `celerp/ai/`, `celerp/cloud/` | Celerp Proprietary | `LICENSE-PROPRIETARY.md` |
-| `celerp/output/` (official document/PDF + public share renderers) | Celerp Proprietary | `LICENSE-PROPRIETARY.md` |
-| `ui/` (application UI layer) | Celerp Proprietary | `LICENSE-PROPRIETARY.md` |
+| `celerp/gateway/`, `celerp/session_gate.py`, `celerp/ai/`, `celerp/cloud/` | Celerp Official Components License (LicenseRef-Proprietary) | `legal/OFFICIAL-COMPONENTS.md` |
+| `celerp/output/` (official document/PDF + public share renderers) | Celerp Official Components License (LicenseRef-Proprietary) | `legal/OFFICIAL-COMPONENTS.md` |
+| `ui/` (application UI layer) | Celerp Official Components License (LicenseRef-Proprietary) | `legal/OFFICIAL-COMPONENTS.md` |
 | `default_modules/celerp-admin/` | Business Source License 1.1 | `LICENSE` |
-| `default_modules/celerp-ai/`, `celerp-backup/`, `celerp-connectors/` | Celerp Proprietary | `LICENSE-PROPRIETARY.md` |
+| `default_modules/celerp-ai/`, `celerp-backup/`, `celerp-connectors/` | Celerp Official Components License (LicenseRef-Proprietary) | `legal/OFFICIAL-COMPONENTS.md` |
 | `default_modules/celerp-accounting/` | MIT | module `LICENSE` |
 | `default_modules/celerp-contacts/` | MIT | module `LICENSE` |
 | `default_modules/celerp-dashboard/` | MIT | module `LICENSE` |
@@ -32,8 +32,8 @@ Notes:
   the license of the engine it requires, and using the engine remains governed by `LICENSE`.
 - **Attribution:** the "Powered by Celerp" mark is produced and required by the proprietary components
   (the official UI and document/PDF rendering layer) and the Cloud Services agreement. It is NOT imposed
-  by the MIT modules - MIT cannot carry that restriction. See `LICENSE-PROPRIETARY.md`.
-- Trademarks are not licensed by any of the above; see `TRADEMARK.md`.
+  by the MIT modules - MIT cannot carry that restriction. See `legal/OFFICIAL-COMPONENTS.md`.
+- Trademarks are not licensed by any of the above; see `legal/TRADEMARK.md`.
 - Third-party dependencies retain their own licenses.
 
 Copyright (c) 2026 Noah Severs.

{celerp-1.2.0 → celerp-1.2.4}/MANIFEST.in

@@ -1,8 +1,10 @@
 include README.md
 include LICENSE
 include NOTICE
+include LICENSING.md
+include legal/OFFICIAL-COMPONENTS.md
+include legal/TRADEMARK.md
 include alembic.ini
-include ui/LICENSE
 include default_modules/celerp-manufacturing/LICENSE
 include default_modules/celerp-labels/LICENSE
 

celerp-1.2.4/NOTICE

@@ -0,0 +1,27 @@
+NOTICE - Celerp
+
+Celerp is distributed under multiple licenses. This NOTICE is an attribution and
+packaging summary; it is not the operative license grant.
+
+  - The full first-party license map is in LICENSING.md, which is authoritative.
+    Where a source file carries an SPDX-License-Identifier header, that header
+    governs that file.
+  - Some official Celerp components are governed by the Celerp Official
+    Components License (SPDX: LicenseRef-Proprietary); see
+    legal/OFFICIAL-COMPONENTS.md.
+  - The source-available engine and the celerp-admin module are under the
+    Business Source License 1.1 (SPDX: BUSL-1.1); see LICENSE.
+  - The default business modules are under the MIT License; see the LICENSE file
+    in each module subdirectory.
+
+Attribution: the "Powered by Celerp" mark in user-visible output is produced and
+required by the official components (the UI and document/PDF rendering layer) and
+the Cloud Services agreement; it is not imposed by the MIT modules.
+
+Trademarks ("Celerp" and the Celerp logo) are not licensed by any code license;
+see legal/TRADEMARK.md.
+
+Third-party components included in packaged desktop builds are governed by their
+own license files; see licenses/.
+
+For commercial, OEM, or white-label inquiries: https://celerp.com

{celerp-1.2.0 → celerp-1.2.4}/PKG-INFO

@@ -1,32 +1,46 @@
 Metadata-Version: 2.4
 Name: celerp
-Version: 1.2.0
+Version: 1.2.4
 Summary: Free, self-hosted ERP for small businesses
 License: Business Source License 1.1
         
+        License text copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved.
+        "Business Source License" is a trademark of MariaDB Corporation Ab.
+        
+        -----------------------------------------------------------------------------
+        
         Parameters
         
         Licensor:             Noah Severs
         Licensed Work:        Celerp
                               The Licensed Work is (c) 2026 Noah Severs
-        Additional Use Grant: You may make production use of the Licensed Work, including
-                              deploying it for your own business operations, provided that
-                              you may not offer the Licensed Work as a hosted service to
-                              third parties (SaaS/PaaS) without a separate commercial
-                              agreement with the Licensor.
+        Additional Use Grant: You may use the Licensed Work in production to operate
+                              Celerp for your own internal business purposes, including
+                              self-hosted use by your company and its affiliates. This
+                              Additional Use Grant does not include offering the Licensed
+                              Work, modified versions of the Licensed Work, or a
+                              substantially similar competing product as a hosted service,
+                              SaaS service, managed service, OEM product, or white-label
+                              product to third parties without a commercial agreement with
+                              Licensor.
         
         Change Date:          2029-01-01
         
         Change License:       Apache License, Version 2.0
         
+        For information about alternative licensing arrangements for the Licensed Work
+        (including commercial licensing, OEM agreements, and white-label inquiries),
+        please contact https://celerp.com.
+        
         -----------------------------------------------------------------------------
         
-        For commercial licensing, OEM agreements, or white-label inquiries:
-        https://celerp.com
+        Notice
         
-        -----------------------------------------------------------------------------
+        The Business Source License (this document, or the "License") is not an Open
+        Source license. However, the Licensed Work will eventually be made available
+        under an Open Source License, as stated in this License.
         
-        Business Source License 1.1
+        -----------------------------------------------------------------------------
         
         Terms
         
@@ -37,19 +51,19 @@ License: Business Source License 1.1
         
         Effective on the Change Date, or the fourth anniversary of the first publicly
         available distribution of a specific version of the Licensed Work under this
-        License, whichever comes first, the Licensor hereby grants you rights under the
-        terms of the Change License, and the rights granted in the paragraph above
-        terminate.
+        License, whichever comes first, the Licensor hereby grants you rights under
+        the terms of the Change License, and the rights granted in the paragraph
+        above terminate.
         
-        If your use of the Licensed Work does not comply with the requirements currently
-        in effect as described in this License, you must purchase a commercial license
-        from the Licensor, its affiliated entities, or authorized resellers, or you must
-        refrain from using the Licensed Work.
+        If your use of the Licensed Work does not comply with the requirements
+        currently in effect as described in this License, you must purchase a
+        commercial license from the Licensor, its affiliated entities, or authorized
+        resellers, or you must refrain from using the Licensed Work.
         
         All copies of the original and modified Licensed Work, and derivative works of
-        the Licensed Work, are subject to this License. This License applies separately
-        for each version of the Licensed Work and the Change Date may vary for each
-        version of the Licensed Work released by the Licensor.
+        the Licensed Work, are subject to this License. This License applies
+        separately for each version of the Licensed Work and the Change Date may vary
+        for each version of the Licensed Work released by Licensor.
         
         You must conspicuously display this License on each original or modified copy
         of the Licensed Work. If you receive the Licensed Work in original or modified
@@ -57,18 +71,45 @@ License: Business Source License 1.1
         apply to your use of that work.
         
         Any use of the Licensed Work in violation of this License will automatically
-        terminate your rights under this License for the current and all other versions
-        of the Licensed Work.
+        terminate your rights under this License for the current and all other
+        versions of the Licensed Work.
         
         This License does not grant you any right in any trademark or logo of Licensor
-        or its affiliates (provided that you may use a trademark or logo of Licensor as
-        expressly required by this License).
+        or its affiliates (provided that you may use a trademark or logo of Licensor
+        as expressly required by this License).
         
         TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN
         "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS
         OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY,
         FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
         
+        MariaDB hereby grants you permission to use this License's text to license
+        your works, and to refer to it using the trademark "Business Source License",
+        as long as you comply with the Covenants of Licensor below.
+        
+        -----------------------------------------------------------------------------
+        
+        Covenants of Licensor
+        
+        In consideration of the right to use this License's text and the "Business
+        Source License" name and trademark, Licensor covenants to MariaDB, and to all
+        other recipients of the licensed work to be provided by Licensor:
+        
+        1. To specify as the Change License the GPL Version 2.0 or any later version,
+           or a license that is compatible with GPL Version 2.0 or a later version,
+           where "compatible" means that software provided under the Change License can
+           be included in a program with software provided under GPL Version 2.0 or a
+           later version. Licensor may specify additional Change Licenses without
+           limitation.
+        
+        2. To either: (a) specify an additional grant of rights to use that does not
+           impose any additional restriction on the right granted in this License, as
+           the Additional Use Grant; or (b) insert the text "None".
+        
+        3. To specify a Change Date.
+        
+        4. Not to modify this License in any other way.
+        
 Project-URL: Homepage, https://celerp.com
 Project-URL: Repository, https://github.com/celerp/celerp
 Project-URL: Documentation, https://celerp.com/docs
@@ -85,7 +126,6 @@ Classifier: Topic :: Office/Business :: Financial :: Accounting
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-License-File: LICENSE-PROPRIETARY.md
 License-File: NOTICE
 Requires-Dist: fastapi>=0.115
 Requires-Dist: uvicorn[standard]>=0.30
@@ -139,6 +179,7 @@ Website: [www.celerp.com](https://www.celerp.com)
 
 Celerp is simple to use, flexible, customizable, and designed to transition your business into the AI age with no technical knowledge needed to setup your whole office. We want to put businesses back in charge of their data.
 
+[![Downloads](https://static.pepy.tech/badge/celerp)](https://pepy.tech/project/celerp)
 [![Tests](https://github.com/celerp/celerp/actions/workflows/ci.yml/badge.svg)](https://github.com/celerp/celerp/actions)
 [![License](https://img.shields.io/badge/license-BUSL--1.1-blue)](LICENSE)
 
@@ -272,5 +313,5 @@ Celerp is open-core:
 - **A proprietary application + cloud layer** (official UI, document/PDF output, and the cloud/AI
   services) that powers the hosted experience.
 
-See [LICENSING.md](LICENSING.md) for the full map and [TRADEMARK.md](TRADEMARK.md) for use of the Celerp
+See [LICENSING.md](LICENSING.md) for the full map and [TRADEMARK.md](legal/TRADEMARK.md) for use of the Celerp
 name. One restriction: don't resell Celerp itself as a competing product.

{celerp-1.2.0 → celerp-1.2.4}/README.md

@@ -8,6 +8,7 @@ Website: [www.celerp.com](https://www.celerp.com)
 
 Celerp is simple to use, flexible, customizable, and designed to transition your business into the AI age with no technical knowledge needed to setup your whole office. We want to put businesses back in charge of their data.
 
+[![Downloads](https://static.pepy.tech/badge/celerp)](https://pepy.tech/project/celerp)
 [![Tests](https://github.com/celerp/celerp/actions/workflows/ci.yml/badge.svg)](https://github.com/celerp/celerp/actions)
 [![License](https://img.shields.io/badge/license-BUSL--1.1-blue)](LICENSE)
 
@@ -141,5 +142,5 @@ Celerp is open-core:
 - **A proprietary application + cloud layer** (official UI, document/PDF output, and the cloud/AI
   services) that powers the hosted experience.
 
-See [LICENSING.md](LICENSING.md) for the full map and [TRADEMARK.md](TRADEMARK.md) for use of the Celerp
+See [LICENSING.md](LICENSING.md) for the full map and [TRADEMARK.md](legal/TRADEMARK.md) for use of the Celerp
 name. One restriction: don't resell Celerp itself as a competing product.

celerp-1.2.4/celerp/ai/intent.py

@@ -0,0 +1,56 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: LicenseRef-Proprietary
+
+"""Intent classification - detect file-through routing tasks.
+
+Determines whether a query with files needs AI comprehension (read the file)
+or is a routing/filing task (skip file content). Keyword-based and instant, so
+classifying intent never costs a metered model call. Ambiguous cases default to
+COMPREHENSION.
+
+If no files are attached, always returns COMPREHENSION.
+"""
+
+from __future__ import annotations
+
+import logging
+
+log = logging.getLogger(__name__)
+
+
+class Intent:
+    COMPREHENSION = "comprehension"
+    ROUTING = "routing"
+
+
+_ROUTING_PATTERNS = (
+    "file this",
+    "save this",
+    "attach this",
+    "store this",
+    "add this to",
+    "put this in",
+    "send this to",
+    "move this to",
+    "archive this",
+)
+
+def _keyword_match(query: str) -> str | None:
+    """Check for routing keywords. Returns Intent or None if ambiguous."""
+    lowered = query.lower()
+    for pattern in _ROUTING_PATTERNS:
+        if pattern in lowered:
+            return Intent.ROUTING
+    return None
+
+
+async def classify_intent(query: str, has_files: bool) -> str:
+    """Classify query intent. Returns Intent.COMPREHENSION or Intent.ROUTING.
+
+    Without files, always returns COMPREHENSION (text queries always need AI).
+    With files, a routing keyword marks a file-only task; otherwise COMPREHENSION.
+    """
+    if not has_files:
+        return Intent.COMPREHENSION
+    result = _keyword_match(query)
+    return result if result is not None else Intent.COMPREHENSION

celerp-1.2.4/celerp/ai/llm.py

@@ -0,0 +1,110 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: LicenseRef-Proprietary
+
+"""LLM client - single entry point for all model calls.
+
+Calls are served through the cloud gateway, which selects the model and meters
+usage. Supports text-only and multimodal (image/PDF) messages.
+Concurrency-limited via a module-level semaphore.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+import httpx
+
+from celerp.gateway.state import relay_http_url, relay_session_headers
+
+log = logging.getLogger(__name__)
+
+_MAX_CONCURRENT = int(os.getenv("AI_MAX_CONCURRENT", "3"))
+_semaphore = asyncio.Semaphore(_MAX_CONCURRENT)
+
+
+def _build_user_content(
+    text: str,
+    files: list[dict] | None = None,
+) -> str | list[dict]:
+    """Build the user message content block.
+
+    Text-only: returns a plain string.
+    With files: returns a list of content parts (image_url or text).
+    Each file dict must have keys: media_type (str), data (base64 str).
+    """
+    if not files:
+        return text
+
+    parts: list[dict] = []
+    for f in files:
+        data_uri = f"data:{f['media_type']};base64,{f['data']}"
+        parts.append({"type": "image_url", "image_url": {"url": data_uri}})
+    parts.append({"type": "text", "text": text})
+    return parts
+
+
+async def call_llm(
+    model: str,
+    system: str,
+    user_text: str,
+    files: list[dict] | None = None,
+    max_tokens: int = 2048,
+    history: list[dict[str, str]] | None = None,
+    timeout: float = 60.0,
+) -> str:
+    """Run a completion through the gateway and return the assistant's text.
+
+    Args:
+        model: advisory only — the gateway selects the served model.
+        history: Optional prior conversation messages [{"role": ..., "content": ...}].
+
+    Raises HTTPException(402) when the plan's quota is exhausted.
+    Raises RuntimeError on other failures (no session, gateway error).
+    """
+    user_content = _build_user_content(user_text, files)
+
+    messages: list[dict] = [{"role": "system", "content": system}]
+    if history:
+        messages.extend(history)
+    messages.append({"role": "user", "content": user_content})
+
+    file_count = len(files) if files else 0
+    body = {
+        "messages": messages,
+        "hints": {
+            "query": user_text[:500],
+            "file_count": file_count,
+            "is_batch": file_count > 1,
+        },
+        "max_tokens": max_tokens,
+    }
+
+    headers = relay_session_headers()
+    if not headers.get("X-Session-Token"):
+        raise RuntimeError("The AI service is not available - no active cloud session.")
+
+    url = f"{relay_http_url()}/ai/complete"
+
+    async with _semaphore:
+        async with httpx.AsyncClient(timeout=timeout) as client:
+            resp = await client.post(url, headers=headers, json=body)
+
+    if resp.status_code == 200:
+        return resp.json().get("answer", "")
+
+    if resp.status_code == 402:
+        from fastapi import HTTPException
+        try:
+            detail = resp.json().get("detail", {})
+        except Exception:
+            detail = {}
+        if not isinstance(detail, dict):
+            detail = {"code": "quota_exceeded", "message": str(detail)}
+        raise HTTPException(status_code=402, detail=detail)
+
+    if resp.status_code in (429, 503):
+        raise RuntimeError("The AI service is temporarily busy.")
+
+    raise RuntimeError(f"LLM gateway error {resp.status_code}")

celerp-1.2.4/celerp/ai/quota.py

@@ -0,0 +1,63 @@
+# Copyright (c) 2026 Noah Severs
+# SPDX-License-Identifier: LicenseRef-Proprietary
+
+"""Gateway quota status client.
+
+Reads AI quota status from the relay for display and tier checks. Quota is
+enforced by the gateway as a query runs; this module only reports it.
+"""
+
+from __future__ import annotations
+
+import logging
+
+import httpx
+
+from celerp.config import settings
+from celerp.gateway.state import (
+    get_session_token,
+    relay_http_url,
+    relay_session_headers,
+)
+
+# Alias so tests / internal callers import this from here rather than reaching
+# into celerp.gateway.state directly.
+_relay_http_url = relay_http_url
+
+log = logging.getLogger(__name__)
+
+
+async def get_subscription_tier() -> str | None:
+    """Fetch the subscription tier for this instance from the relay.
+
+    Returns the tier string (e.g. "cloud", "ai", "team") or None if:
+      - gateway is not configured (local install)
+      - relay is unreachable
+      - subscription is not active
+
+    Never raises — callers treat None as "no restriction".
+    """
+    status = await get_quota_status()
+    return status.get("tier") if status else None
+
+
+async def get_quota_status() -> dict | None:
+    """Fetch full AI quota status from the relay.
+
+    Returns dict with keys: allowed, used, limit, topup_credits, resets_at, tier.
+    Returns None if gateway not configured or relay unreachable.
+    """
+    if not settings.gateway_token or not get_session_token():
+        return None
+
+    url = f"{relay_http_url()}/quota/ai/status"
+
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            r = await client.get(url, headers=relay_session_headers())
+        if r.status_code == 200:
+            return r.json()
+        log.warning("Quota status returned %s", r.status_code)
+    except Exception as exc:
+        log.warning("Failed to fetch quota status: %s", exc)
+    return None