HippoDb Agent SDK

Python SDK for building AI agents backed by HippoDb.

Homepage: https://luthen.ai/

This package is designed for developers who want to build custom agents with:

• an LLM tool-use loop
• persistent memory in HippoDb
• configurable business tools
• optional rule enforcement, gateway, and networking features

What This SDK Provides

• AgentRunner to boot and run an agent
• RoleConfig to define agent identity and prompt behavior
• BaseTool to define business-domain tools
• AgentSettings to configure runtime behavior
• built-in memory, OS, and calculator tools
• HippoDb-backed memory client and memory seeding support
• BaseAgent for hosts that serve their own web or API transport (streaming, stop, per-message reasoning effort)

Documentation

The full list is in docs/README.md. The documents ship inside the package: after pip install, run python -m hippodb_agent docs to find them, or python -m hippodb_agent docs --open to open the release notes.

Core Concepts

1. Role

A role defines what the agent is, which tools it can see, and how it should behave.

2. Tools

Tools are Python classes that inherit from BaseTool. They are how the agent interacts with external systems.

3. Runner

AgentRunner wires together the LLM, tools, HippoDb, configuration, and terminal runtime.

4. Memory

HippoDb acts as the persistent memory layer for concepts, rules, and conversation continuity.

Installation

pip install hippodb-agent-sdk

For local development against a source checkout:

pip install -e .

Configuration

Configuration is loaded from:

1. the defaults in AgentSettings (src/hippodb_agent/config.py)
2. local .env
3. environment variables

Important settings include:

• LLM_API_KEY
• ANTHROPIC_API_KEY
• HIPPODB_URL
• HIPPODB_API_KEY (only when HippoDb sits behind a manager that enforces API keys)
• MODEL
• LLM_REASONING_EFFORT (low, medium or high; empty uses the model's default)
• HISTORY_WINDOW, MAX_TOTAL_TOOLS, MAX_ROUNDS (how much one LLM call carries)

Every setting is listed in section 17 of the technical reference.

Example .env:

LLM_API_KEY=your_key_here
HIPPODB_URL=http://localhost:7700
MODEL=anthropic/claude-sonnet-4-20250514

Minimal Example

Create a small agent with one custom tool.

tools.py

from hippodb_agent import BaseTool


class HelloTool(BaseTool):
    name = "demo_hello"
    description = "Return a hello message"
    input_schema = {
        "type": "object",
        "properties": {},
        "required": [],
    }

    async def execute(self, inp: dict) -> dict:
        return {"message": "hello from HippoDb Agent SDK"}

role.py

from hippodb_agent import RoleConfig


MY_ROLE = RoleConfig(
    name="demo_agent",
    display_name="Demo Agent",
    tool_scopes=["demo_"],
    fabric="demo_agent",
    system_prompt="You are a helpful demo agent.\n\n{manifest}",
)

main.py

from hippodb_agent import AgentRunner
from role import MY_ROLE
from tools import HelloTool


runner = AgentRunner(
    role=MY_ROLE,
    business_tools=[HelloTool],
)


if __name__ == "__main__":
    runner.start()

Run it with:

python main.py

Building a New Agent

For a typical agent project, you usually create:

• tools.py for business-domain tools
• role.py for RoleConfig
• main.py as the startup entry point
• seed.yaml for pre-education
• test_suite.py or tests for validation

Example Tool

from hippodb_agent import BaseTool


class ListEmployees(BaseTool):
    name = "hr_list_employees"
    description = "List all employees"
    input_schema = {"type": "object", "properties": {}, "required": []}
    backend = "hr"

    async def execute(self, inp: dict) -> dict:
        r = await self.api.get("/employees")
        r.raise_for_status()
        return r.json()

Example Runner With Backend

from hippodb_agent import AgentRunner
from role import MY_ROLE
from tools import ListEmployees


runner = AgentRunner(
    role=MY_ROLE,
    business_tools=[ListEmployees],
    api_base_url="http://localhost:9000",
    seed_file="seed.yaml",
)


if __name__ == "__main__":
    runner.start()

Public SDK Surface

The intended primary imports are:

from hippodb_agent import (
    AgentSettings,
    RoleConfig,
    AgentRunner,
    BaseTool,
    ApiClients,
)

Typed errors, all importable from hippodb_agent: HippoDbError, HippoTimeoutError, FabricNotFoundError, EngineCapabilityRemovedError, and LlmError with its subclasses (LlmRateLimitError, LlmOverloadedError, LlmConnectionError, LlmTimeoutError, LlmAuthError, LlmContextWindowError, LlmBadRequestError).

A host that builds the agent itself (instead of using AgentRunner) also uses from hippodb_agent.core.agent import BaseAgent, from hippodb_agent.memory.client import HippoClient, from hippodb_agent.tools.registry import ToolRegistry and from hippodb_agent.tools.discovery import ToolDiscovery; see the host-integration guide.

Additional helper exports currently include:

• get_os_tools
• get_calc_tools
• BaseMemoryFormatter
• get_formatter
• DataGateway
• MaskStrategy
• FieldPolicy
• AgentNetwork

Runtime Behavior

Installing this package does not start any worker or background service.

Runtime behavior begins only when your application starts an agent, typically through AgentRunner.start().

Depending on configuration, startup may:

• connect to HippoDb
• create or reuse a fabric
• seed memory from seed.yaml
• connect to the optional agent network

Notes

• This repository currently includes some optional subsystems beyond the core SDK, such as networking, gateway/compliance, and monitoring.
• The primary use of the package is as an SDK for building custom agents.
• See CHANGELOG.md for release history and docs/releases/release-notes-2.0.0.html for the 2.0.0 feature overview and upgrade guide.
• Bundled utility applications may exist in the repository, but they are not required for SDK usage.

Development

Useful local commands:

pip install -e .[dev]
pytest

License

This SDK is distributed under the PolyForm Noncommercial License 1.0.0. In short:

• Free to install, run, modify, and evaluate for any noncommercial purpose (personal projects, research, internal evaluation, etc.)
• Any commercial use requires a separate license from us.

See LICENSE for the full terms.

For commercial licensing inquiries, contact darshana@behaviol.com.

This technology is created and owned by Behaviol Pvt Ltd, distributed under the product name Luthen (https://luthen.ai/).