Ask AI assistant widget for Sphinx

Add a Biel.ai AI assistant or AI search widget to your Sphinx documentation using the sphinx-biel package. Works with any Sphinx theme, including Read the Docs. You can also connect AI agents through MCP, with or without installing the widget.

Prerequisites

• A Biel.ai account.
• A project with indexed content.
• A Sphinx project.

Add the assistant widget

The sphinx-biel extension adds a floating chat button to your site.

1. Install the package:

   pip install sphinx-biel

2. Add the extension to your conf.py:

   extensions = ['sphinx_biel']

3. Configure your project ID in conf.py:

   biel_project = '<YOUR_PROJECT_ID>'
   biel_header_title = 'Biel.ai assistant'
   biel_version = 'latest'

   Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

4. Build and verify:

   make html

   Open the built documentation in a browser and verify the assistant appears.

Add the search widget

The search widget replaces the theme's search box with Biel.ai's AI-powered search. Enable sphinx-biel to load the widget assets, then override the search template.

1. Install and configure the extension:

   pip install sphinx-biel

   In conf.py, append sphinx_biel to your existing extensions and set your project ID:

   extensions = ['sphinx_biel']
   biel_project = '<YOUR_PROJECT_ID>'
   biel_header_title = 'Documentation AI'

2. Create _templates/searchbox.html in your project with the following content:

   <biel-search-button project="<YOUR_PROJECT_ID>" button-style="rounded" header-title="Documentation AI">
     Search
   </biel-search-button>

   Replace <YOUR_PROJECT_ID> with your project's ID from the Biel.ai dashboard.

3. Make sure conf.py points at your templates directory:

   templates_path = ["_templates"]

4. Rebuild and verify the search widget appears where the theme's search box was (the sidebar on the Read the Docs theme).

Select a widget version

The extension loads the widget's JavaScript and CSS from the CDN using latest by default. You do not need to install an npm widget package. Your Python dependencies do not pin these browser assets.

To use a specific widget release, add this to conf.py and rebuild with make html:

biel_version = '0.1.93'

Replace 0.1.93 with a published biel-search version on npm. Set biel_version = 'latest' to follow new releases again. See CDN version selection for how caching affects latest.

Customization

Pass layout options in conf.py with these naming conventions:

• Prefix each option with biel_ (e.g., project → biel_project).
• Replace hyphens with underscores (e.g., button-position → biel_button_position).

biel_button_style = "light"
biel_button_position = "center-right"

Connect AI agents with MCP

Let AI tools search and read your indexed documentation. MCP is available on every plan and during your trial.

1. In the Biel.ai dashboard, open your project’s Settings > MCP.
2. Select Enable MCP server and click Save.
3. In the widget, open Connect via MCP using the <> button. Select your AI client or choose MCP URL to copy the endpoint into its settings.

Without the widget: after enabling MCP, copy MCP endpoint from Settings > MCP and add it to your AI client. No widget installation or website changes are required.

The widget also exposes WebMCP tools to compatible browser agents visiting your site. Use the latest widget release and keep Enable WebMCP selected in Settings > MCP.

Next steps

• View the sphinx-biel source and releases.
• Customize the widget's appearance, behavior, and tone.
• Connect integrations like GitHub Actions, MCP, or Zapier.