harborrag-core

The provider-neutral foundation of HarborRAG: domain models, protocol contracts, storage schemas, and security helpers. It has no provider SDK dependencies, so importing it pulls in nothing heavy and performs no I/O.

Every other HarborRAG package depends on this one. You rarely install it alone - install harborrag instead - but you import from it whenever you write an adapter or type a function signature against HarborRAG data.

pip install harborrag-core

What it exports

from harborrag_core import Document, HarborError, RetrievalQuery, RetrievalResult

Deeper contracts stay in submodules rather than the package root:

Contributing to this package

• Add only stable, dependency-light contracts here.
• Keep provider SDKs out of this package.
• Add protocols in harborrag_core.ports.* when adapters need a shared model contract; model-client protocols live in harborrag_core.ports.model_clients.
• Add domain models in harborrag_core.domain.* only when multiple packages need them.
• Reuse StrictModel or ExtensibleModel from harborrag_core.base for validated models.
• Add package-wide exceptions to harborrag_core.contracts.errors; keep subsystem error families near their subsystem.

Hard rule: harborrag-core must never import harborrag-adapters, harborrag-engine, harborrag-runtime, harborrag-app, harborrag-mcp-server, or the harborrag meta-package. scripts/check_dependency_direction.py enforces this in CI.

Development

Tests for this package live in packages/harborrag-core/tests/. Run them from the repository root:

uv run pytest packages/harborrag-core/tests

See Extending HarborRAG for how contracts here relate to adapter implementations.

Licensed under the Apache License 2.0.