NucliaDB Agentic API

The NucliaDB Agentic API package exposes NucliaDB-oriented agentic capabilities for Hyperforge, including ASK/search flows and MCP integrations.

Install

From the workspace root:

uv sync

Run

Start the service:

uv run nucliadb-agentic-api

Useful endpoints:

/health/ready
/health/alive
/metrics

Configuration

Runtime configuration is provided through environment variables consumed by Pydantic settings. Common settings include:

HTTP_HOST and HTTP_PORT
MEMORY_READER_NUCLIADB, MEMORY_WRITER_NUCLIADB, and MEMORY_SEARCH_NUCLIADB
MEMORY_APIKEY_NUCLIADB
VALKEY_URL
IDP_REGIONAL_GRPC
LOAD_MODULES

Development

Run the package tests from the workspace root:

make test

Objective

Enhance the RAG experience by offering RAO features directly in a KB.

How?

The same way we store search configs in the KB, we could store agentic configs, and when calling the /ask endpoint we can refer to a given agentic config.

Scope

The corresponding RAO workflow will be:

a Rephrase (optionally)
a SmartAgent
a Summarize

Possible sources for the SmartAgent:

The current KB (possibly several times with different filters)
Sync service (using connections defined in the current KB)
Google
Perplexity
MCP

Out of scope

Other KBs
SQL
Snowflake (?)
Sitefinity (?)

Config spec

{
  "rephrase": { // optional
    "ask_to": <filter_expression>, //optional
    "prompt": <string>, // optional
    "model": <model>, // optional
  },
  "smart_agent": {
    "mode": <reactive | plan_execute>,
    "extra_prompt": <string>, // optional
    "models": { // optional
      "context_validation": <model>, // optional
      "planner": <model>, // optional
      "executor": <model>, // optional
    },
    "sources": [<source list>]
  },
  "summarize": { // optional
    "user_prompt": <string>, // optional
    "system_prompt": <string>, // optional
    "conversational": <boolean>,
    "model": <model>, // optional
    // and citations must be forced to chunk-level
  }
}

And sources can be:

{
  "type": "nucliadb",
  "description": <string>,
  "search_config": <ask search configuration id>, // optional
  "filter_expression": <filter_expression>, //optional
}

{
  "type": "sync",
  "description": <string>,
  "connection": <connection_id>
}

{
  "type": "google",
  "description": <string>
}

{
  "type": "perplexity",
  "description": <string>
}

{
  "type": "mcp",
  "description": <string>,
  <...the MCP driver params>
}

Metadata

Release files for nucliadb-agentic-api 1.0.0.post251

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for nucliadb-agentic-api 1.0.0.post251
File	Size	Uploaded
nucliadb_agentic_api-1.0.0.post251.tar.gz	42.4 kB	Aug 24, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for nucliadb-agentic-api 1.0.0.post251
File	Interpreter	ABI	Platform	Reset
nucliadb_agentic_api-1.0.0.post251-py3-none-any.whl 51.0 kB Aug 24, 2026	Python 3	none	any	Details

Total release size: 93.4 kB

Release files / nucliadb_agentic_api-1.0.0.post251.tar.gz

Download URL	nucliadb_agentic_api-1.0.0.post251.tar.gz
Size	42.4 kB
Tags	Source
SHA-256 checksum How to use checksums	`e611cd6ec79053ee9971c7d874434e6531f6ba5cb528e7eb8748e6bba7dda285`
BLAKE2b-256 checksum How to use checksums	`d478cd5b5b6e246b74eec2e0cf1150042dc8090b9dc074a8902bb2607d83f4cd`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/nucliadb_agentic_api
Publishing commit: github.com/nuclia/nucliadb_agentic_api/tree/237dd8554e15d68efab8a60f7d30dcb2ede33f71

Workflow

Publishing configuration: github.com/nuclia/nucliadb_agentic_api/blob/237dd8554e15d68efab8a60f7d30dcb2ede33f71/.github/workflows/nucliadb_agentic_api_workflow.yaml
Publishing logs: github.com/nuclia/nucliadb_agentic_api/actions/runs/32712828339/attempts/1

Artifact

Subject: nucliadb_agentic_api-1.0.0.post251.tar.gz
SHA-256 checksum: e611cd6ec79053ee9971c7d874434e6531f6ba5cb528e7eb8748e6bba7dda285 Verifying attestations

Release files / nucliadb_agentic_api-1.0.0.post251-py3-none-any.whl

Download URL	nucliadb_agentic_api-1.0.0.post251-py3-none-any.whl
Size	51.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`7f7b507f62eb51b47e48f3aeed7c5be09d8dcb397e83f74938be4ce4f088190e`
BLAKE2b-256 checksum How to use checksums	`c6c354914a229a215de04df52e9ae7222f8e90bd5bbbf10bb126bcb71663c9c6`
Upload date	Aug 24, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.13`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/nuclia/nucliadb_agentic_api
Publishing commit: github.com/nuclia/nucliadb_agentic_api/tree/237dd8554e15d68efab8a60f7d30dcb2ede33f71

Workflow

Publishing configuration: github.com/nuclia/nucliadb_agentic_api/blob/237dd8554e15d68efab8a60f7d30dcb2ede33f71/.github/workflows/nucliadb_agentic_api_workflow.yaml
Publishing logs: github.com/nuclia/nucliadb_agentic_api/actions/runs/32712828339/attempts/1

Artifact

Subject: nucliadb_agentic_api-1.0.0.post251-py3-none-any.whl
SHA-256 checksum: 7f7b507f62eb51b47e48f3aeed7c5be09d8dcb397e83f74938be4ce4f088190e Verifying attestations