andnp-searchkernel

andnp-searchkernel is a source-agnostic Python library for building hybrid keyword, vector, and graph search systems. Applications map their native data to canonical Record values, choose the storage and provider adapters they need, and keep source-specific lifecycle logic outside the kernel.

It supports canonical record search, checkpointed record ingestion, optional local/Postgres/FAISS/provider integrations, and bounded federation across compatible search sources. Breaking changes are documented per release in docs/upgrading.md.

Install

The core package supports Python 3.13 and newer:

pip install andnp-searchkernel

Install optional integrations only when you need them:

pip install "andnp-searchkernel[faiss]"
pip install "andnp-searchkernel[pgvector]"
pip install "andnp-searchkernel[pgvector-psycopg3]"
pip install "andnp-searchkernel[huggingface]"
pip install "andnp-searchkernel[ollama]"
pip install "andnp-searchkernel[markdown]"

First local search

The local composition helper creates durable SQLite-backed stores. This small example uses a deterministic provider so it can run without downloading a model; replace it with a real provider for semantic retrieval.

import asyncio
from datetime import UTC, datetime
from pathlib import Path

from searchkernel import Record, build_local_record_kernel


class DemoEmbeddingProvider:
    model_name = "demo"
    dim = 2

    def embed(self, texts: list[str]) -> list[list[float]]:
        return [[1.0, 0.0] for _ in texts]


async def main() -> None:
    timestamp = datetime.now(UTC)
    composition = build_local_record_kernel(
        Path("records.db"),
        embedding_provider=DemoEmbeddingProvider(),
    )
    record = Record(
        workspace_id="demo",
        source_kind="notes",
        source_id="welcome",
        title="Welcome",
        body="Canonical records can be searched locally.",
        created_at=timestamp,
        updated_at=timestamp,
    )
    composition.keyword_store.index([record])

    outcome = await composition.kernel.search("canonical records", limit=5)
    for result in outcome.results:
        print(result.record.title, result.score)


asyncio.run(main())

The result is a RecordSearchOutcome. Each result retains the complete workspace/source identity and search provenance; degraded execution is reported through outcome.failures and outcome.diagnostics.

Documentation

Start with the documentation map to choose the right guide:

  • Getting started — install the package and build a first local index.
  • Core concepts — records, identity, ingestion, querying, stores, providers, and readiness.
  • Federated search — combine local or HTTP search sources with bounded concurrency and explicit partial-result diagnostics.
  • Performance and retrieval roadmap — developer-facing validation evidence, constraints, and future work.

Optional integrations

The core import surface does not require optional providers or backends. The available extras are faiss, pgvector, pgvector-psycopg3, huggingface, ollama, and markdown. See the getting-started guide for the selection rule and the federation guide for the HTTP source adapter.

Validation and releases

CI runs Ruff, Pyrefly, import-linter, the safe test suite, supported Python versions, and selected optional-import checks. Pgvector integration tests need Docker or SEARCHKERNEL_PG_DSN; real-embedding tests are outside the default offline gate. The performance roadmap records what those checks do and do not prove.

Merges to main with release-worthy Conventional Commits are released by the repository workflows. The package and runtime __version__ are checked against each other in CI and before semantic release.

License

MIT. See LICENSE.

Project links

Data verified by PyPI on Aug 20, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.11.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for andnp from gravatar.com andnp

GitHub Statistics

Data verified by PyPI on Aug 20, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.13

Provides Extra

faiss huggingface markdown ollama pgvector pgvector-psycopg3

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

andnp_searchkernel-1.7.0.tar.gz (610.4 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

andnp_searchkernel-1.7.0-py3-none-any.whl (288.0 kB view details)

Uploaded Python 3

File details

Details for the file andnp_searchkernel-1.7.0.tar.gz.

File metadata

  • Download URL: andnp_searchkernel-1.7.0.tar.gz
  • Upload date:
  • Size: 610.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for andnp_searchkernel-1.7.0.tar.gz
Algorithm Hash digest
SHA256 3ca5fc9dfe2acf0a5574d045021f3196045aa242bc59b83ccf4140a5a72391aa
MD5 b967ab19422508540b7fdb2df6a951c4
BLAKE2b-256 8298f53ec6809b45175793eb548e7d29679443c9bfbad33f1beadf3e84f08ded

See more details on using hashes here.

Provenance

The following attestation bundles were made for andnp_searchkernel-1.7.0.tar.gz:

Publisher: publish.yml on andnp/andnp-searchkernel

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file andnp_searchkernel-1.7.0-py3-none-any.whl.

File metadata

File hashes

Hashes for andnp_searchkernel-1.7.0-py3-none-any.whl
Algorithm Hash digest
SHA256 5337c7330007d40dcc7044efcd87e93213185050a14867689352a3fa275c93ea
MD5 902740a9cc0f4c32155eaa7964b85e78
BLAKE2b-256 a98c3fd320c6a5de856e23d6ab8f46db28c290725c33d17a383c173c6da933c9

See more details on using hashes here.

Provenance

The following attestation bundles were made for andnp_searchkernel-1.7.0-py3-none-any.whl:

Publisher: publish.yml on andnp/andnp-searchkernel

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

1.11.0

2 files

1.10.0

2 files

1.9.1

2 files

1.9.0

2 files

1.8.1

2 files

1.8.0

2 files

This release

1.7.0 This release

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.0

2 files

1.3.0

2 files

1.2.0

2 files

1.1.0

2 files

1.0.0

2 files

0.25.0

2 files

0.24.0

2 files

0.23.0

2 files

0.22.0

2 files

0.21.0

2 files

0.20.0

2 files

0.19.0

2 files

0.18.0

2 files

0.17.0

2 files

0.16.0

2 files

0.15.8

2 files

0.15.7

2 files

0.15.6

2 files

0.15.5

2 files

0.15.4

2 files

0.15.3

2 files

0.15.2

2 files

0.15.1

2 files

0.15.0

2 files

0.14.0

2 files

0.13.3

2 files

0.13.2

2 files

0.13.1

2 files

0.13.0

2 files

0.12.0

2 files

0.11.1

2 files

0.11.0

2 files

0.10.0

2 files

0.9.1

2 files

0.9.0

2 files

0.8.0

2 files

0.7.0

2 files

0.6.0

2 files

0.5.0

2 files

0.4.1

2 files

0.4.0

2 files

0.3.0

2 files

0.2.0

2 files

0.1.0

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page