Module AI API and the import boundary

If you reached this page from an error when Celerp loaded a module, that module tried to import one of Celerp's internal components directly. This page explains which imports are allowed, which are not, and how to do what you were trying to do the supported way.

What modules may import

Module code can freely use Celerp's public building blocks:

  • celerp.db - get_session for an async database session.
  • celerp.services.auth - get_current_user and get_current_company_id dependencies.
  • celerp.models.base - the shared Base your tables inherit from.
  • celerp.modules.api - the public module API: api_request, read_resource and ai_query.

What modules may not import

The loader checks each module's files before running any of its code, and refuses to load a module it finds importing these internals or anything under them:

  • celerp.session_gate
  • celerp.ai or anything under it
  • celerp.gateway
  • celerp.connectors

These sit behind Celerp's licensing and usage metering. Importing them directly would bypass those gates, so Celerp refuses to load a module it finds importing them. This keeps community modules cleanly on the open side of the line, which is also what lets them stay MIT-licensed and freely shareable.

Using AI the supported way

If your module needs AI - drafting text, classifying, answering questions over the user's data - call ai_query from celerp.modules.api:

from celerp.modules.api import ai_query

result = await ai_query(query, company_id, db_session=session)
answer = result["answer"]

Its full signature is ai_query(query, company_id, session_token=None, db_session=None). Pass the database session of the request the query is made for: the query runs only for that request's company and for a role allowed to use the AI assistant, and otherwise it is refused. It routes through the same metering and model access as the built-in AI features, so your module works for users who have AI enabled without touching gated internals.

Independent AI inference is not an approvable integration. A module that runs a model itself or calls an AI service directly is not admitted to the Community catalog or the marketplace; use ai_query instead.

Fixing the error

  1. Find the import the loader named in its message.
  2. Replace a direct celerp.ai import with ai_query from celerp.modules.api.
  3. If you were reaching into celerp.gateway or celerp.connectors, note that connector sync and relay access are Connect features, not part of the module surface; there is no supported module path into them today.
  4. Run python lint.py your-module/ from the template - it flags protected imports before you restart.

For the full module walkthrough, see Build a module.