Data models and shared libraries

models/ and lib/ contain shared Python used by the agent bundle. Unlike tools, subagents, MCP clients, and extensions, neither folder is capability discovery.

Folder	Put here	Import from	Discovered as a capability?
`models/`	Pydantic contracts	`harnest.models`	No
`lib/`	Reusable Python	`harnest.lib`	No

`models/`

Put shared Pydantic contracts under root models/ and import them through the compiler-owned harnest.models namespace. For example, models/orders.py becomes harnest.models.orders:

models/orders.py

from pydantic import BaseModel


class OrderStatus(BaseModel):
    order_id: str
    status: str

Use these contracts for agent, graph, tool, and client-tool input or output. The folder is root-only and needs no __init__.py.

Accept multimodal data

Validate images, audio, video, files, and custom data with Pydantic.

Store and retrieve media

Choose a named store and access scoped assets.

`lib/`

Put ordinary reusable implementation under root lib/ and import it through harnest.lib. For example, lib/storage/queries.py becomes harnest.lib.storage.queries, while the discovered tool stays under tools/:

def load_order(order_id: str) -> dict:
    """Load one order from application storage."""

    return {"order_id": order_id, "status": "processing"}

from harnest.lib.storage.queries import load_order
from harnest.agent import tool


@tool
def lookup_order(order_id: str) -> dict:
    """Load one order."""

    return load_order(order_id)

Library functions do not become tools or agents by themselves. The same namespace works in compilation, tests, evals, and serving. lib/ is root-only. Add third-party packages used by either namespace to the agent’s pyproject.toml. Add __init__.py only for intentional library initialization, not to make discovery work.

Overview

Get started

Guides

Data models and shared libraries

`models/`

Accept multimodal data

Store and retrieve media

`lib/`

​models/

Accept multimodal data

Store and retrieve media

​lib/

`models/`

`lib/`