Connector SDK Overview

The Hoard Connector SDK provides everything you need to build custom data source connectors.

What Is a Connector?

A connector is a plugin that imports data from a source into Hoard. Connectors:

• Implement the ConnectorV1 interface
• Emit canonical types (EntityInput, ChunkInput)
• Are reviewed before inclusion in recommended list
• Can be distributed via the community connectors repo

Connector Types

Type	Description	Auth	Difficulty
Export	Reads exported files (ZIP, JSON)	None	Easy
Local	Reads local files/databases	Filesystem	Easy
Live	Syncs via API	OAuth/Token	Hard

Installation

The SDK is included with Hoard:

pip install hoard

Quick Start

1. Create Connector

from hoard.sdk import ConnectorV1, EntityInput, ChunkInput, DiscoverResult
from hoard.sdk import chunk_plain_text, compute_content_hash
from pathlib import Path
from typing import Iterator, Tuple, List

class MyConnector(ConnectorV1):

    @property
    def name(self) -> str:
        return "my_connector"

    @property
    def version(self) -> str:
        return "1.0.0"

    @property
    def source_name(self) -> str:
        return "my_source"

    def discover(self, config: dict) -> DiscoverResult:
        path = Path(config["data_path"]).expanduser()
        if not path.exists():
            return DiscoverResult(success=False, message=f"Not found: {path}")
        files = list(path.glob("*.txt"))
        return DiscoverResult(success=True, entity_count_estimate=len(files))

    def scan(self, config: dict) -> Iterator[Tuple[EntityInput, List[ChunkInput]]]:
        path = Path(config["data_path"]).expanduser()
        for file in path.glob("*.txt"):
            content = file.read_text()
            entity = EntityInput(
                source=self.source_name,
                source_id=str(file.absolute()),
                entity_type="document",
                title=file.stem,
                content_hash=compute_content_hash(content),
            )
            chunks = [
                ChunkInput(content=c.text, char_offset_start=c.start, char_offset_end=c.end)
                for c in chunk_plain_text(content)
            ]
            yield entity, chunks

2. Create Manifest

manifest.yaml

name: my_connector
version: "1.0.0"
description: "Import text files"
author: "Your Name"
license: "MIT"

requires_hoard: ">=1.0.0"

config_schema:
  type: object
  required: [data_path]
  properties:
    data_path:
      type: string

entry_point: "connector:MyConnector"

3. Test It

# Test your connector manually
connector = MyConnector()
config = {"data_path": "fixtures/sample"}

result = connector.discover(config)
assert result.success

for entity, chunks in connector.scan(config):
    print(f"{entity.title}: {len(chunks)} chunks")

SDK Components

Module	Purpose
hoard.sdk.base	ConnectorV1 interface
hoard.sdk.types	EntityInput, ChunkInput, DiscoverResult
hoard.sdk.chunking	chunk_plain_text(), ChunkSpan
hoard.sdk.hash	compute_content_hash()

All exports are also available from hoard.sdk directly.

Security Note

Caution

In v1, connectors are trusted code. They run in the same process as Hoard core. Installing a connector means trusting its author.

Permissions in manifests are informational only — they document what the connector needs but are not enforced at runtime.

Contribution Workflow

1. Implement ConnectorV1 interface
2. Add manifest and tests
3. Submit PR to connectors repo
4. Code review (security-aware)
5. Added to recommended list after approval

Next Steps

• ConnectorV1 Interface — Full interface spec
• Types — EntityInput, ChunkInput details
• Utilities — Chunking and text helpers
• Testing — Test harness usage