Metadata-Version: 2.5
Name: harborrag
Version: 2.0.0a1
Summary: Meta-package public facade for HarborRAG.
Project-URL: Homepage, https://github.com/cbtw-apac/HarborRAG
Project-URL: Repository, https://github.com/cbtw-apac/HarborRAG
Project-URL: Issues, https://github.com/cbtw-apac/HarborRAG/issues
Author: HarborRAG Contributors
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: harborrag-core==2.0.0a1
Requires-Dist: harborrag-runtime==2.0.0a1
Provides-Extra: all
Requires-Dist: harborrag-adapters[parsers-all]==2.0.0a1; extra == 'all'
Requires-Dist: harborrag-app[api]==2.0.0a1; extra == 'all'
Requires-Dist: harborrag-mcp-server[mcp]==2.0.0a1; extra == 'all'
Requires-Dist: harborrag-memory==2.0.0a1; extra == 'all'
Requires-Dist: harborrag-runtime[production,temporal]==2.0.0a1; extra == 'all'
Provides-Extra: chat
Requires-Dist: harborrag-adapters[llm]==2.0.0a1; extra == 'chat'
Provides-Extra: cli
Requires-Dist: harborrag-app==2.0.0a1; extra == 'cli'
Provides-Extra: falkordb
Requires-Dist: harborrag-adapters[falkordb]==2.0.0a1; extra == 'falkordb'
Provides-Extra: local
Requires-Dist: harborrag-adapters[chunking,control-plane,falkordb,llm,parsers,pdf-docling,qdrant,s3,tables]==2.0.0a1; extra == 'local'
Provides-Extra: mcp
Requires-Dist: harborrag-mcp-server[mcp]==2.0.0a1; extra == 'mcp'
Provides-Extra: memory
Requires-Dist: harborrag-memory==2.0.0a1; extra == 'memory'
Provides-Extra: postgres
Requires-Dist: harborrag-adapters[control-plane,postgres]==2.0.0a1; extra == 'postgres'
Provides-Extra: qdrant
Requires-Dist: harborrag-adapters[qdrant]==2.0.0a1; extra == 'qdrant'
Provides-Extra: redis
Requires-Dist: harborrag-adapters[redis]==2.0.0a1; extra == 'redis'
Provides-Extra: s3
Requires-Dist: harborrag-adapters[s3]==2.0.0a1; extra == 's3'
Provides-Extra: server
Requires-Dist: harborrag-app[api]==2.0.0a1; extra == 'server'
Requires-Dist: harborrag-runtime[production,temporal]==2.0.0a1; extra == 'server'
Provides-Extra: temporal
Requires-Dist: harborrag-runtime[temporal]==2.0.0a1; extra == 'temporal'
Description-Content-Type: text/markdown

# harborrag

`harborrag` is the public SDK facade and installation bundle for
[HarborRAG](https://github.com/cbtw-apac/HarborRAG), a modular, provider-agnostic RAG
framework for engineering knowledge. Importing it does not initialize provider clients or
perform network I/O.

- Documentation: <https://cbtw-apac.github.io/HarborRAG/>
- Source: <https://github.com/cbtw-apac/HarborRAG>

## Install

```bash
pip install "harborrag[all]"          # everything
pip install "harborrag[local]"        # local end-to-end ingestion and retrieval
pip install "harborrag[cli,qdrant]"   # or just what you need
```

A bare `pip install harborrag` installs the framework - contracts, engine, memory,
adapters, and runtime - but deliberately **no third-party provider clients**. There is no
vector store, no graph store, and no model client until you add an extra:

| Extra | Adds |
| --- | --- |
| `local` | Qdrant, FalkorDB, S3, model client, chunking, control plane, parsers, Docling PDF, tables |
| `chat` | the model client used by chat, embeddings, and reranking |
| `cli` | the `harborrag` command |
| `server` | the HTTP API plus the production and Temporal runtime |
| `mcp` | the MCP transport |
| `temporal` | the Temporal client for durable ingestion |
| `qdrant`, `falkordb`, `postgres`, `s3`, `redis` | one provider each |
| `all` | everything above; a superset of `local` |

Conversation memory (`harborrag-memory`) is already a required dependency, so it is
available in every install. The `harborrag[memory]` extra exists for explicitness and adds
nothing new.

See [Installation](https://cbtw-apac.github.io/HarborRAG/docs/getting-started/installation.html)
for PDF/OCR backends, editable installs, and platform notes.

## Ingest and retrieve

`HarborRAG` exposes four async service facades - `ingestion`, `retrieval`, `graph`, and
`chat` - behind one async context manager. Connectors are declared by name in your
connector catalog, so credentials stay as environment references:

```python
import asyncio

from harborrag import AccessContext, HarborRAG, IngestionRequest, RetrievalRequest


async def main() -> None:
    access = AccessContext(principal_id="user-1", tenant_id="tenant-1")

    async with HarborRAG.from_config("config/harborrag.example.yaml") as harbor:
        await harbor.ingestion.run(
            IngestionRequest(access=access, connector_name="harborrag-workspace")
        )
        results = await harbor.retrieval.search(
            RetrievalRequest(access=access, query="deployment requirements")
        )
        print(results)


asyncio.run(main())
```

`config/harborrag.example.yaml` ships in the repository checkout. Copy it next to your
application and point `from_config` at your own path.

## Chat

Chat needs a model provider, so install `harborrag[chat]` (or any extra that includes it,
such as `local`, `server`, or `all`) and configure credentials first:

```python
from harborrag import ChatPrompt, HarborChatMessage, HarborChatRequest, HarborRAG

async with HarborRAG.from_config("config/harborrag.example.yaml") as harbor:
    response = await harbor.chat.complete(
        HarborChatRequest(messages=(HarborChatMessage.user("Summarize the results"),)),
        prompt=ChatPrompt.CONCISE,
    )
```

## Direct versus durable execution

Direct execution is the default: `ingestion.run` does the work inline.

The durable controls - `submit`, `status`, `pause`, `resume`, and `cancel` - need
`execution_mode: temporal` in your configuration **and** the `harborrag[temporal]` extra.
Calling them without both raises `ExecutionCapabilityError`:

```python
task = await harbor.ingestion.submit(request)
status = await harbor.ingestion.status(task.task_id)
await harbor.ingestion.pause(task.task_id)
await harbor.ingestion.resume(task.task_id)
await harbor.ingestion.cancel(task.task_id)
```

## Related packages

`harborrag` re-exports stable APIs from the workspace packages. Install one directly for a
narrower dependency tree:

| Package | Contains |
| --- | --- |
| `harborrag-core` | provider-neutral contracts and domain models |
| `harborrag-adapters` | connectors, parsers, model clients, repositories |
| `harborrag-engine` | ingestion and retrieval orchestration |
| `harborrag-memory` | scope-aware conversation memory |
| `harborrag-runtime` | production composition and Temporal orchestration |
| `harborrag-app` | CLI and HTTP API |
| `harborrag-mcp-server` | MCP tools and transport |

## Development

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

```shell
uv run pytest packages/harborrag/tests
```

Licensed under the Apache License 2.0.
