> ## Documentation Index
> Fetch the complete documentation index at: https://usefused.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Data models and shared libraries

> Share Pydantic contracts and ordinary Python implementation across an agent bundle.

`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`:

```python models/orders.py theme={null}
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`.

<CardGroup cols={2}>
  <Card title="Accept multimodal data" icon="shapes" href="/docs/harnest/build/models-and-libraries/typed-multimodal-contracts">
    Validate images, audio, video, files, and custom data with Pydantic.
  </Card>

  <Card title="Store and retrieve media" icon="database" href="/docs/harnest/build/models-and-libraries/store-and-retrieve-media">
    Choose a named store and access scoped assets.
  </Card>
</CardGroup>

## `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/`:

<CodeGroup>
  ```python lib/storage/queries.py theme={null}
  def load_order(order_id: str) -> dict:
      """Load one order from application storage."""

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

  ```python tools/lookup_order.py theme={null}
  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)
  ```
</CodeGroup>

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.