HippoDb Agent SDK

Python SDK for building self-tuning 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, tuning, 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

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. SDK defaults in src/hippodb_agent/defaults.env
2. local .env
3. environment variables

Important settings include:

• LLM_API_KEY
• ANTHROPIC_API_KEY
• HIPPODB_URL
• MODEL

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,
)

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
• start internal scheduler tasks
• connect to the optional agent network

Notes

• This repository currently includes some optional subsystems beyond the core SDK, such as networking, gateway/compliance, tuning, monitoring, and sleep orchestration.
• The primary use of the package is as an SDK for building custom agents.
• 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/).