lorebo-sdk 0.1.0__py3-none-any.whl

lorebo_sdk/client.py

@@ -0,0 +1,119 @@
+from typing import Any, Self
+
+from fastmcp import Client
+from fastmcp.exceptions import ToolError
+from pydantic import BaseModel, ValidationError
+from pydantic_ai.models import Model, infer_model
+
+from lorebo_sdk.errors import LockedBaseError, LoreboToolError
+from lorebo_sdk.records import Base, CaptureResult, ExploreResult
+from lorebo_sdk.runs import CaptureReport, ExploreReport, SkillRunner
+from lorebo_sdk.skills import PublishedSkills, Skill, SkillSource
+
+
+class ListedBase(BaseModel):
+    base_ref: str
+    label: str
+    kind: str
+    entry_id: str
+
+
+class BaseList(BaseModel):
+    items: list[ListedBase]
+
+
+class CreatedBase(BaseModel):
+    entry_id: str
+
+
+class Lorebo:
+    def __init__(
+        self,
+        mcp_client: Client[Any],
+        model: Model,
+        skills: SkillSource,
+        base_ref: str | None,
+    ) -> None:
+        self._mcp_client = mcp_client
+        self._base_ref = base_ref
+        self._runner = SkillRunner(model, skills, mcp_client, base_ref)
+
+    @classmethod
+    def from_url(
+        cls,
+        *,
+        url: str,
+        token: str | None,
+        model: Model | str,
+        base_ref: str | None,
+    ) -> Self:
+        return cls(
+            mcp_client=Client(url, auth=token),
+            model=infer_model(model),
+            skills=PublishedSkills(),
+            base_ref=base_ref,
+        )
+
+    async def capture(self, prompt: str) -> CaptureResult:
+        run = await self._runner.run(Skill.CAPTURE, prompt, CaptureReport)
+
+        return CaptureResult(
+            summary=run.report.summary,
+            created=run.pages.created,
+            updated=run.pages.updated,
+        )
+
+    async def explore(self, prompt: str) -> ExploreResult:
+        run = await self._runner.run(Skill.EXPLORE, prompt, ExploreReport)
+
+        return ExploreResult(
+            answer=run.report.answer,
+            sources=run.pages.cited(run.report.source_page_ids),
+        )
+
+    async def list_bases(self) -> list[Base]:
+        listed_bases = await self._list_bases()
+
+        return [
+            Base(base_ref=listed.base_ref, label=listed.label, kind=listed.kind)
+            for listed in listed_bases
+        ]
+
+    async def create_base(self, label: str, path: str, activate: bool) -> Base:
+        if self._base_ref is not None:
+            raise LockedBaseError("base_create_base", self._base_ref)
+
+        created = await self._call_tool(
+            "base_create_base",
+            {"display_name": label, "path": path, "activate": activate},
+            CreatedBase,
+        )
+        listed_bases = await self._list_bases()
+
+        for listed in listed_bases:
+            if listed.entry_id == created.entry_id:
+                return Base(base_ref=listed.base_ref, label=listed.label, kind=listed.kind)
+
+        raise LoreboToolError("base_create_base", f"base {created.entry_id} is not listed")
+
+    async def _list_bases(self) -> list[ListedBase]:
+        base_list = await self._call_tool("working_base_list_bases", {}, BaseList)
+
+        return base_list.items
+
+    async def _call_tool[ResponseT: BaseModel](
+        self,
+        tool_name: str,
+        arguments: dict[str, Any],
+        response_type: type[ResponseT],
+    ) -> ResponseT:
+        try:
+            async with self._mcp_client:
+                result = await self._mcp_client.call_tool(tool_name, arguments)
+        except ToolError as error:
+            raise LoreboToolError(tool_name, str(error)) from error
+
+        try:
+            return response_type.model_validate(result.structured_content)
+        except ValidationError as error:
+            raise LoreboToolError(tool_name, "the response has an unexpected shape") from error

lorebo_sdk/errors.py

@@ -0,0 +1,29 @@
+class LoreboError(Exception):
+    pass
+
+
+class LockedBaseError(LoreboError):
+    def __init__(self, tool_name: str, base_ref: str) -> None:
+        self.tool_name = tool_name
+        self.base_ref = base_ref
+
+        super().__init__(f"{tool_name} tried to leave the locked base {base_ref}")
+
+
+class LoreboToolError(LoreboError):
+    def __init__(self, tool_name: str, detail: str) -> None:
+        self.tool_name = tool_name
+        self.detail = detail
+
+        super().__init__(f"{tool_name} failed: {detail}")
+
+
+class SkillPackageError(LoreboError):
+    pass
+
+
+class RunLimitError(LoreboError):
+    def __init__(self, request_limit: int) -> None:
+        self.request_limit = request_limit
+
+        super().__init__(f"the run did not finish within {request_limit} model requests")

lorebo_sdk/pages.py

@@ -0,0 +1,92 @@
+from pydantic import BaseModel, ValidationError
+
+from lorebo_sdk.errors import LoreboToolError
+from lorebo_sdk.records import Page
+
+
+class PageReference(BaseModel):
+    id: str
+    title: str
+
+
+class PageItems(BaseModel):
+    items: list[PageReference]
+
+
+class HybridSearchResults(BaseModel):
+    results: list[PageReference]
+
+
+class RelevantSubgraph(BaseModel):
+    nodes: list[PageReference]
+
+
+class RunPages:
+    CREATING_TOOLS = frozenset({"create_page"})
+    UPDATING_TOOLS = frozenset({"update_page", "replace_in_page"})
+    SINGLE_PAGE_TOOLS = frozenset({"get_page"})
+    PAGE_ITEMS_TOOLS = frozenset({"get_pages", "list_pages", "search", "find_similar_notes"})
+
+    def __init__(self) -> None:
+        self._created: dict[str, Page] = {}
+        self._updated: dict[str, Page] = {}
+        self._seen: dict[str, Page] = {}
+
+    @property
+    def created(self) -> list[Page]:
+        return list(self._created.values())
+
+    @property
+    def updated(self) -> list[Page]:
+        return list(self._updated.values())
+
+    def cited(self, page_ids: list[str]) -> list[Page]:
+        pages: dict[str, Page] = {}
+
+        for page_id in page_ids:
+            page = self._seen.get(page_id)
+
+            if page is not None:
+                pages[page.id] = page
+
+        return list(pages.values())
+
+    def record(self, tool_name: str, base_ref: str, payload: object) -> None:
+        references = RunPages.page_references(tool_name, payload)
+        pages = [
+            Page(id=reference.id, title=reference.title, base_ref=base_ref)
+            for reference in references
+        ]
+
+        for page in pages:
+            self._seen[page.id] = page
+
+            if tool_name in RunPages.CREATING_TOOLS:
+                self._created[page.id] = page
+
+            if tool_name in RunPages.UPDATING_TOOLS:
+                changed_pages = self._created if page.id in self._created else self._updated
+                changed_pages[page.id] = page
+
+    @staticmethod
+    def page_references(tool_name: str, payload: object) -> list[PageReference]:
+        try:
+            if (
+                tool_name in RunPages.CREATING_TOOLS
+                or tool_name in RunPages.UPDATING_TOOLS
+                or tool_name in RunPages.SINGLE_PAGE_TOOLS
+            ):
+                return [PageReference.model_validate(payload)]
+
+            if tool_name in RunPages.PAGE_ITEMS_TOOLS:
+                return PageItems.model_validate(payload).items
+
+            if tool_name == "hybrid_search":
+                return HybridSearchResults.model_validate(payload).results
+
+            if tool_name == "get_relevant_subgraph":
+                return RelevantSubgraph.model_validate(payload).nodes
+        except ValidationError as error:
+            raise LoreboToolError(tool_name, "the response does not describe pages") from error
+
+        return []

lorebo_sdk/records.py

@@ -0,0 +1,32 @@
+from pydantic import BaseModel, ConfigDict
+
+
+class Page(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    id: str
+    title: str
+    base_ref: str
+
+
+class Base(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    base_ref: str
+    label: str
+    kind: str
+
+
+class CaptureResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    summary: str
+    created: list[Page]
+    updated: list[Page]
+
+
+class ExploreResult(BaseModel):
+    model_config = ConfigDict(frozen=True)
+
+    answer: str
+    sources: list[Page]

lorebo_sdk/runs.py

@@ -0,0 +1,164 @@
+from dataclasses import dataclass
+from typing import Any
+
+import pydantic_ai
+from fastmcp import Client
+from pydantic import BaseModel, Field
+from pydantic_ai import Agent, RunContext
+from pydantic_ai.exceptions import UsageLimitExceeded
+from pydantic_ai.mcp import CallToolFunc, MCPToolset, ToolResult
+from pydantic_ai.models import Model
+from pydantic_ai.tools import ToolDefinition
+from pydantic_ai.usage import UsageLimits
+
+from lorebo_sdk.errors import RunLimitError
+from lorebo_sdk.pages import RunPages
+from lorebo_sdk.skills import Skill, SkillSource
+from lorebo_sdk.tools import SkillToolPolicy
+
+
+class CaptureReport(BaseModel):
+    summary: str = Field(
+        description=(
+            "One or two plain sentences for the application's user: "
+            "what was saved, or why nothing was saved."
+        )
+    )
+
+
+class ExploreReport(BaseModel):
+    answer: str = Field(
+        description="The answer to the prompt in plain text, based on the Lorebo pages read."
+    )
+    source_page_ids: list[str] = Field(description="IDs of the Lorebo pages the answer relies on.")
+
+
+class BaseScopedArguments(BaseModel):
+    base_ref: str
+
+
+@dataclass(frozen=True)
+class SkillRun[ReportT: BaseModel]:
+    report: ReportT
+    pages: RunPages
+
+
+class SkillRunner:
+    REQUEST_LIMIT = 24
+
+    def __init__(
+        self,
+        model: Model,
+        skills: SkillSource,
+        mcp_client: Client[Any],
+        base_ref: str | None,
+    ) -> None:
+        self._model = model
+        self._skills = skills
+        self._mcp_client = mcp_client
+        self._base_ref = base_ref
+
+        pydantic_ai.BANNER_ENABLED = False
+
+    async def run[ReportT: BaseModel](
+        self,
+        skill: Skill,
+        prompt: str,
+        report_type: type[ReportT],
+    ) -> SkillRun[ReportT]:
+        skill_instructions = await self._skills.instructions(skill)
+        policy = SkillToolPolicy(skill, self._base_ref)
+        pages = RunPages()
+
+        async def call_lorebo_tool(
+            context: RunContext[None],
+            call_tool: CallToolFunc,
+            tool_name: str,
+            arguments: dict[str, Any],
+        ) -> ToolResult:
+            prepared_arguments = policy.prepare_arguments(tool_name, arguments)
+            result = await call_tool(tool_name, prepared_arguments)
+
+            if SkillToolPolicy.is_base_scoped(tool_name):
+                base_ref = BaseScopedArguments.model_validate(prepared_arguments).base_ref
+                pages.record(tool_name, base_ref, result)
+
+            return result
+
+        def is_available(context: RunContext[None], tool: ToolDefinition) -> bool:
+            return policy.allows(tool.name)
+
+        toolset: MCPToolset[None] = MCPToolset(
+            self._mcp_client,
+            process_tool_call=call_lorebo_tool,
+        )
+        agent = Agent(
+            self._model,
+            instructions=SkillRunner.instructions(skill, skill_instructions, self._base_ref),
+            output_type=report_type,
+            deps_type=type(None),
+            toolsets=[toolset.filtered(is_available)],
+        )
+
+        try:
+            result = await agent.run(
+                prompt,
+                usage_limits=UsageLimits(request_limit=SkillRunner.REQUEST_LIMIT),
+            )
+        except UsageLimitExceeded as error:
+            raise RunLimitError(SkillRunner.REQUEST_LIMIT) from error
+
+        return SkillRun(report=result.output, pages=pages)
+
+    @staticmethod
+    def instructions(skill: Skill, skill_instructions: str, base_ref: str | None) -> str:
+        if base_ref is not None:
+            base_rule = (
+                f"This run is locked to the base {base_ref}. "
+                "Pass that base_ref on every call that takes one. Other bases are not available."
+            )
+        elif skill is Skill.CAPTURE:
+            base_rule = (
+                "No base is preselected. List the bases and choose the one this knowledge "
+                "belongs to, or create one when none fits. Pass its base_ref on every call "
+                "that takes one."
+            )
+        else:
+            base_rule = (
+                "No base is preselected. List the bases and choose the one that holds this "
+                "knowledge. Pass its base_ref on every call that takes one."
+            )
+
+        if skill is Skill.CAPTURE:
+            final_report_rule = (
+                "Its summary is shown to the application's user. State what was saved, or why "
+                "nothing was saved."
+            )
+        else:
+            final_report_rule = (
+                "Its answer is shown to the application's user. Answer the prompt directly from "
+                "the pages you read, and put the IDs of the pages it relies on in "
+                "source_page_ids instead of listing sources in the answer."
+            )
+
+        return "\n\n".join(
+            [
+                skill_instructions,
+                "# Lorebo SDK run",
+                (
+                    f"You are running the {skill} skill for an application through the Lorebo "
+                    "SDK. The run is unattended: nobody can answer questions or confirm steps. "
+                    "The application's prompt is the whole task and its only source material."
+                ),
+                base_rule,
+                (
+                    "Governance tools read Lorebo's managed governance base. "
+                    "They do not change the target base."
+                ),
+                (
+                    f"When the work is done, return the final report. {final_report_rule} "
+                    "Write that text plainly, without Markdown, page IDs, tool names, or a "
+                    "description of your reasoning and steps."
+                ),
+            ]
+        )

lorebo_sdk/skills.py

@@ -0,0 +1,101 @@
+import hashlib
+import io
+import zipfile
+from enum import StrEnum
+from typing import Protocol
+
+import httpx
+
+from lorebo_sdk.errors import SkillPackageError
+
+
+class Skill(StrEnum):
+    CAPTURE = "lorebo-capture"
+    EXPLORE = "lorebo-explore"
+
+
+class SkillSource(Protocol):
+    async def instructions(self, skill: Skill) -> str: ...
+
+
+class PublishedSkills:
+    VERSION = "0.4.3"
+    DOWNLOAD_URL = "https://downloads.lorebo.com/lorebo/skills/stable"
+    DOWNLOAD_TIMEOUT_SECONDS = 30
+    DIGESTS = {
+        Skill.CAPTURE: "6b3d47ca5ba8f0511fc6b6ce33a22ed34757cd54fec54e06d7f34d3452d5572d",
+        Skill.EXPLORE: "2310e6ef43d68e79641c0b32a0f2cefab141e07cdf322d8ded5c52b7d71c215b",
+    }
+
+    def __init__(self) -> None:
+        self._instructions: dict[Skill, str] = {}
+
+    async def instructions(self, skill: Skill) -> str:
+        cached = self._instructions.get(skill)
+
+        if cached is not None:
+            return cached
+
+        package = await self._download(skill)
+        digest = hashlib.sha256(package).hexdigest()
+
+        if digest != PublishedSkills.DIGESTS[skill]:
+            raise SkillPackageError(f"{skill} {PublishedSkills.VERSION} does not match its digest")
+
+        instructions = SkillPackage.read_instructions(package, skill)
+        self._instructions[skill] = instructions
+
+        return instructions
+
+    async def _download(self, skill: Skill) -> bytes:
+        version = PublishedSkills.VERSION
+        url = f"{PublishedSkills.DOWNLOAD_URL}/{version}/{skill}-{version}.zip"
+
+        try:
+            async with httpx.AsyncClient(
+                follow_redirects=True,
+                timeout=PublishedSkills.DOWNLOAD_TIMEOUT_SECONDS,
+            ) as client:
+                response = await client.get(url)
+                response.raise_for_status()
+        except httpx.HTTPError as error:
+            raise SkillPackageError(f"could not download {url}") from error
+
+        return response.content
+
+
+class SkillPackage:
+    INSTRUCTIONS_FILE = "SKILL.md"
+
+    @staticmethod
+    def read_instructions(package: bytes, skill: Skill) -> str:
+        prefix = f"{skill}/"
+
+        try:
+            archive = zipfile.ZipFile(io.BytesIO(package))
+        except zipfile.BadZipFile as error:
+            raise SkillPackageError(f"{skill} package is not a zip archive") from error
+
+        documents: dict[str, str] = {}
+
+        with archive:
+            for entry in archive.infolist():
+                if entry.is_dir():
+                    continue
+
+                path = entry.filename
+
+                if not path.startswith(prefix) or ".." in path.split("/") or "\\" in path:
+                    raise SkillPackageError(f"{skill} package contains an unexpected path: {path}")
+
+                if path.endswith(".md"):
+                    documents[path.removeprefix(prefix)] = archive.read(entry).decode("utf-8")
+
+        skill_document = documents.pop(SkillPackage.INSTRUCTIONS_FILE, None)
+
+        if skill_document is None:
+            raise SkillPackageError(f"{skill} package has no {SkillPackage.INSTRUCTIONS_FILE}")
+
+        references = [f"# {path}\n\n{text}" for path, text in sorted(documents.items())]
+
+        return "\n\n".join([skill_document, *references])

lorebo_sdk/tools.py

@@ -0,0 +1,87 @@
+from typing import Any
+
+from lorebo_sdk.errors import LockedBaseError
+from lorebo_sdk.skills import Skill
+
+
+class SkillToolPolicy:
+    GOVERNANCE_TOOLS = frozenset(
+        {
+            "get_governance_scenario",
+            "get_governance_scenarios_for_tool",
+        }
+    )
+    BASE_DISCOVERY_TOOLS = frozenset(
+        {
+            "working_base_list_bases",
+            "working_base_get_current_base",
+        }
+    )
+    BASE_CREATION_TOOLS = frozenset(
+        {
+            "base_create_base",
+        }
+    )
+    READ_TOOLS = frozenset(
+        {
+            "get_page",
+            "get_pages",
+            "list_pages",
+            "search",
+            "hybrid_search",
+            "get_relevant_subgraph",
+            "find_similar_notes",
+            "get_page_ancestry",
+            "get_inline_link",
+            "get_graph_counts",
+            "search_capability_status",
+            "get_note_authoring_preferences",
+        }
+    )
+    WRITE_TOOLS = frozenset(
+        {
+            "create_page",
+            "update_page",
+            "replace_in_page",
+            "link_pages",
+            "batch_link",
+            "set_parent",
+        }
+    )
+
+    def __init__(self, skill: Skill, base_ref: str | None) -> None:
+        self._base_ref = base_ref
+        self._available_tools = SkillToolPolicy.available_tools(skill, base_ref)
+
+    def allows(self, tool_name: str) -> bool:
+        return tool_name in self._available_tools
+
+    def prepare_arguments(self, tool_name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+        if self._base_ref is None or not SkillToolPolicy.is_base_scoped(tool_name):
+            return arguments
+
+        requested_base_ref = arguments.get("base_ref")
+
+        if requested_base_ref is not None and requested_base_ref != self._base_ref:
+            raise LockedBaseError(tool_name, self._base_ref)
+
+        return {**arguments, "base_ref": self._base_ref}
+
+    @staticmethod
+    def is_base_scoped(tool_name: str) -> bool:
+        return tool_name in SkillToolPolicy.READ_TOOLS or tool_name in SkillToolPolicy.WRITE_TOOLS
+
+    @staticmethod
+    def available_tools(skill: Skill, base_ref: str | None) -> frozenset[str]:
+        tools = SkillToolPolicy.GOVERNANCE_TOOLS | SkillToolPolicy.READ_TOOLS
+
+        if skill is Skill.CAPTURE:
+            tools |= SkillToolPolicy.WRITE_TOOLS
+
+        if base_ref is None:
+            tools |= SkillToolPolicy.BASE_DISCOVERY_TOOLS
+
+        if base_ref is None and skill is Skill.CAPTURE:
+            tools |= SkillToolPolicy.BASE_CREATION_TOOLS
+
+        return tools

lorebo_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,297 @@
+Metadata-Version: 2.5
+Name: lorebo-sdk
+Version: 0.1.0
+Summary: Save and retrieve Lorebo knowledge from your application with any LLM
+Project-URL: Homepage, https://github.com/lexrag/lorebo-sdk
+Project-URL: Documentation, https://github.com/lexrag/lorebo-sdk#quick-start
+Project-URL: Repository, https://github.com/lexrag/lorebo-sdk
+Project-URL: Issues, https://github.com/lexrag/lorebo-sdk/issues
+Author: LexRAG
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,knowledge-base,llm,lorebo,mcp,pydantic-ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: fastmcp-slim[client]>=4.1
+Requires-Dist: httpx>=0.28
+Requires-Dist: pydantic-ai-slim[mcp]>=2.59
+Requires-Dist: pydantic>=2.11
+Provides-Extra: anthropic
+Requires-Dist: pydantic-ai-slim[anthropic]>=2.59; extra == 'anthropic'
+Provides-Extra: bedrock
+Requires-Dist: pydantic-ai-slim[bedrock]>=2.59; extra == 'bedrock'
+Provides-Extra: google
+Requires-Dist: pydantic-ai-slim[google]>=2.59; extra == 'google'
+Provides-Extra: groq
+Requires-Dist: pydantic-ai-slim[groq]>=2.59; extra == 'groq'
+Provides-Extra: mistral
+Requires-Dist: pydantic-ai-slim[mistral]>=2.59; extra == 'mistral'
+Provides-Extra: openai
+Requires-Dist: pydantic-ai-slim[openai]>=2.59; extra == 'openai'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://github.com/lexrag/lorebo-sdk">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/lexrag/lorebo-sdk/main/assets/lorebo-logo-on-dark.svg">
+      <img src="https://raw.githubusercontent.com/lexrag/lorebo-sdk/main/assets/lorebo-logo-primary.svg" width="264" alt="Lorebo">
+    </picture>
+  </a>
+</p>
+
+<h1 align="center">Lorebo SDK</h1>
+
+<p align="center"><strong>Give your application a knowledge base that people and AI share.</strong></p>
+
+<p align="center">
+  <a href="https://github.com/lexrag/lorebo-sdk/actions/workflows/check.yml"><img src="https://github.com/lexrag/lorebo-sdk/actions/workflows/check.yml/badge.svg" alt="Checks"></a>
+  <a href="https://github.com/lexrag/lorebo-sdk/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-593EDC" alt="MIT license"></a>
+  <a href="https://pypi.org/project/lorebo-sdk/"><img src="https://img.shields.io/badge/Python-3.12+-3776AB" alt="Python 3.12+"></a>
+  <a href="https://www.npmjs.com/package/lorebo-sdk"><img src="https://img.shields.io/badge/TypeScript-Node_22+-3178C6" alt="TypeScript, Node 22+"></a>
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#results">Results</a> ·
+  <a href="#choosing-a-base">Choosing a base</a> ·
+  <a href="#errors">Errors</a> ·
+  <a href="#connecting-to-lorebo">Connecting to Lorebo</a>
+</p>
+
+Lorebo turns useful AI work into knowledge you own:
+readable, connected pages that people and AI agents can find, correct and reuse.
+
+The Lorebo SDK lets your application use that knowledge with two calls:
+
+- **`capture`** saves the durable part of a text as Lorebo pages. It searches
+  first, updates pages that already cover the topic and creates the rest.
+- **`explore`** answers a question from the pages in Lorebo and returns the
+  pages the answer relies on.
+
+Both calls run the official Lorebo skills with the language model you choose.
+The SDK is available for Python and TypeScript with the same behavior.
+
+## Requirements
+
+- A Lorebo MCP endpoint:
+  - Lorebo Desktop serves `http://127.0.0.1:8757/mcp` on your machine.
+  - [Lorebo Headless](https://github.com/orgs/lexrag/packages/container/package/lorebo-headless) serves `http://127.0.0.1:8758/mcp` when run locally with the example below.
+- A language model that supports tool calls and structured output.
+- Python 3.12+ or Node.js 22+.
+
+## Connecting to Lorebo
+
+With Desktop already running, use its local MCP URL in the quick start.
+To run Headless with Docker instead:
+
+```bash
+docker run --detach --name lorebo \
+  --publish 127.0.0.1:8758:8758 \
+  --volume lorebo-data:/data \
+  ghcr.io/lexrag/lorebo-headless:stable
+```
+
+Use `http://127.0.0.1:8758/mcp` as the SDK URL and `None` (`null` in
+TypeScript) as the token. The volume preserves your bases when the container
+is recreated. Back up the complete volume before upgrading and stop the old
+container before starting another writer on it. The official image is Linux
+amd64; ARM hosts need amd64 emulation.
+
+For a remote deployment, use the HTTPS URL and authentication configured by
+your deployment operator. The SDK's `token` argument sends an optional HTTP
+Bearer token; it does not configure the server's authentication or perform
+Lorebo broker OAuth sign-in. Keep the native server behind the authenticated
+deployment perimeter. No provider API key or Lorebo credential belongs in source
+code; configure model-provider credentials through the provider's environment
+settings.
+
+## Quick start
+
+### Python
+
+```bash
+pip install "lorebo-sdk[openai]"
+```
+
+The extra installs the model provider. `anthropic`, `google`, `groq`,
+`mistral` and `bedrock` are available too.
+
+```python
+import asyncio
+
+from lorebo_sdk.client import Lorebo
+
+
+async def main() -> None:
+    lorebo = Lorebo.from_url(
+        url="http://127.0.0.1:8757/mcp",
+        token=None,
+        model="openai:gpt-5-mini",
+        base_ref="local:your-entry-id",
+    )
+
+    captured = await lorebo.capture("Our API listens on port 8757, on loopback only.")
+    print(captured.summary)
+
+    explored = await lorebo.explore("Which port does our API use?")
+    print(explored.answer)
+
+
+asyncio.run(main())
+```
+
+`model` accepts any [Pydantic AI](https://ai.pydantic.dev/models/) model or model name.
+
+### TypeScript
+
+```bash
+npm install lorebo-sdk ai @ai-sdk/openai
+```
+
+```ts
+import { openai } from "@ai-sdk/openai";
+import { createLorebo } from "lorebo-sdk";
+
+const lorebo = createLorebo({
+  url: "http://127.0.0.1:8757/mcp",
+  token: null,
+  model: openai("gpt-5-mini"),
+  baseRef: "local:your-entry-id",
+});
+
+const captured = await lorebo.capture("Our API listens on port 8757, on loopback only.");
+console.log(captured.summary);
+
+const explored = await lorebo.explore("Which port does our API use?");
+console.log(explored.answer);
+```
+
+`model` accepts any [AI SDK](https://ai-sdk.dev/providers) language model.
+
+## Results
+
+`capture` returns what changed in Lorebo:
+
+| Field     | Meaning                             |
+| --------- | ----------------------------------- |
+| `summary` | One or two sentences for your user. |
+| `created` | Pages this call created.            |
+| `updated` | Existing pages this call changed.   |
+
+`explore` returns the answer and its sources:
+
+| Field     | Meaning                                             |
+| --------- | --------------------------------------------------- |
+| `answer`  | Plain-text answer for your user.                    |
+| `sources` | Pages the answer relies on, each read in this call. |
+
+Each page has an `id`, a `title` and the `base_ref` (`baseRef` in TypeScript)
+of the base that holds it. The SDK builds these lists from Lorebo's responses,
+not from the model's text, so they only contain pages that exist.
+
+Summaries and answers are plain text written for your user, without the model's
+reasoning, tool names or page IDs. Nothing is printed to your console.
+
+## Choosing a base
+
+A Lorebo installation can hold several knowledge bases. Pass `base_ref` to
+lock every call to one of them:
+
+```python
+lorebo = Lorebo.from_url(..., base_ref="local:your-entry-id")
+```
+
+When the model tries to use another base, the call stops with
+`LockedBaseError` before anything is written there.
+
+With multi-base permissions, pass `None` (`null` in TypeScript) to let the skill choose. `capture` then
+picks the base the knowledge belongs to, or creates one when none fits.
+`explore` picks the base that holds the answer.
+
+For a local Headless container, run `docker exec lorebo lorebo-headless --json
+base list` and use `local:<entry_id>` for the active base. Desktop also displays
+the base reference on Base Home. Use the registry entry ID, not the database's
+logical base ID.
+
+When the server exposes multi-base MCP tools, list bases with an unlocked client:
+
+```python
+for base in await lorebo.list_bases():
+    print(base.base_ref, base.label)
+```
+
+```ts
+for (const base of await lorebo.listBases()) {
+  console.log(base.baseRef, base.label);
+}
+```
+
+`create_base` (`createBase` in TypeScript) creates a base from your code.
+Actions remain subject to the connected runtime's account entitlements and
+agent permissions for each base.
+On Free, lock the client to the active base; multi-base discovery and base
+creation through MCP require the corresponding Pro permissions.
+
+## What the model can do
+
+The model only sees the Lorebo tools its skill needs:
+
+- `explore` can read and search pages.
+- `capture` can also create, update and link pages.
+- Without a locked base, both can list bases and `capture` can create one when
+  the connected runtime exposes and permits those tools.
+
+Tools that delete pages, delete bases, restore backups or change sharing are
+never offered.
+
+## Errors
+
+Every SDK error extends `LoreboError`:
+
+| Error               | Raised when                                                    |
+| ------------------- | -------------------------------------------------------------- |
+| `LockedBaseError`   | The model tried to use a base other than the locked one.       |
+| `LoreboToolError`   | Lorebo rejected a call or returned an unexpected response.     |
+| `RunLimitError`     | The skill did not finish within the step limit of 24.          |
+| `SkillPackageError` | A Lorebo skill could not be downloaded or failed verification. |
+
+Python imports them from `lorebo_sdk.errors`, TypeScript from `lorebo-sdk/errors`.
+Errors from the model provider are passed through unchanged.
+
+## Lorebo skills
+
+Each SDK release is pinned to one version of the official `lorebo-capture`
+and `lorebo-explore` skills. They are downloaded from `downloads.lorebo.com`
+on first use, checked against a SHA-256 digest built into the SDK and kept in
+memory for the life of the client.
+
+## Development
+
+```bash
+uv sync
+uv run mypy
+uv run ruff check .
+uv run pytest
+```
+
+```bash
+cd typescript
+npm ci
+npm run check
+npm run build
+npm pack --dry-run
+```
+
+Package publication is described in
+[Releasing](https://github.com/lexrag/lorebo-sdk/blob/main/docs/releasing.md).
+
+## License
+
+[MIT](https://github.com/lexrag/lorebo-sdk/blob/main/LICENSE)

lorebo_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+lorebo_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lorebo_sdk/client.py,sha256=G1Iw2H5iNw_3op652XW3QDEBoqDoGuWvNzRFh0g6nM8,3673
+lorebo_sdk/errors.py,sha256=RiIauXYtRXSYaIRqfcAEPZxmpamIDtWIhcdrTvjasvk,785
+lorebo_sdk/pages.py,sha256=7nYwrFM6d_1cfYjNzwFwWiBAlJTpnmvLtTkxqGk6kIg,2847
+lorebo_sdk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+lorebo_sdk/records.py,sha256=w_qYzqCLXrb4byyjxpIUZJvsiyp2N_S42iNgJ60rCJ4,534
+lorebo_sdk/runs.py,sha256=D4bicJvXMiTJQ6_X4FdugwsNIOacYeK4jFF9jE7tJps,5767
+lorebo_sdk/skills.py,sha256=h6tnZD_s3FXGsU4skbjsz0q1hWZ-uOzAqtcAdpEgnXw,3214
+lorebo_sdk/tools.py,sha256=95HOL6KwNrCIWiYJmNb6lnkrLsA3TwcXMQ6QBQTjeWc,2573
+lorebo_sdk-0.1.0.dist-info/METADATA,sha256=KSGCmFl7FKA8G8MMrrMtXMZyg6fc5J-ssAcKfNhM2VY,10693
+lorebo_sdk-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+lorebo_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=g9c4PDxetLCEzy3TE3wP2ERFj1sNY9QOrCYvGlJsaRU,1063
+lorebo_sdk-0.1.0.dist-info/RECORD,,

lorebo_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

lorebo_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LexRAG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.