### Setup Project Dependencies

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/09_CustomAuth/README.md

Commands to navigate to the example directory and install required Python dependencies.

```sh
cd examples/09_CustomAuth
pip install -r requirements.txt
```

--------------------------------

### Setup Environment

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/08_ConfigStore/README.md

Commands to install dependencies and configure the API key.

```sh
cd examples/08_ConfigStore
pip install -r requirements.txt
```

```text
OPENAI_API_KEY=sk-...
```

--------------------------------

### Server Output Example

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/02_Chat/README.md

Example output when the LLAMPHouse server starts successfully.

```text
LLAMPHOUSE We have light!
LLAMPHOUSE Server: http://127.0.0.1:8000
```

--------------------------------

### Install Prerequisites and Start Redis

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/10_DistributedWorker/README.md

Install project dependencies and start a Redis container required for distributed mode.

```bash
pip install -r requirements.txt

# Redis (only needed for distributed mode)
docker run -d --name redis -p 6379:6379 redis:7-alpine
```

--------------------------------

### Clone and Navigate to Tool Call Example

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/04_ToolCall/README.md

Initializes the local environment by cloning the repository and entering the specific example directory.

```bash
git clone https://github.com/llamp-ai/llamphouse.git
cd llamphouse/examples/04_ToolCall
```

--------------------------------

### Install LLAMPHouse from Source

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/installation.md

Install LLAMPHouse from its GitHub repository for development or to use the latest unreleased features. This includes setting up a virtual environment and installing development dependencies.

```bash
git clone https://github.com/llamp-ai/llamphouse.git
cd llamphouse
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

--------------------------------

### Start Docker Compose

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/07_Tracing/README.md

Start ClickHouse and the OTel Collector using Docker Compose.

```bash
cd ../../docker
docker compose up -d clickhouse otel-collector
```

--------------------------------

### Quick Start Docker Compose Deployment

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/deployment.md

Use this command to quickly start all supporting services for LLAMPHouse in a production-like environment using Docker Compose.

```bash
cd docker
docker compose up -d
```

--------------------------------

### Start Local Postgres for Migrations

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/deployment.md

Commands to start a local PostgreSQL instance using Docker and create the necessary database for LLAMPHouse migrations.

```bash
# Start a local Postgres
docker run --rm -d --name postgres \
  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password \
  -p 5432:5432 postgres
docker exec -it postgres psql -U postgres -c 'CREATE DATABASE llamphouse;'
```

--------------------------------

### Ignite Method

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Shows how to start the LLAMPHouse application server with specified host, port, and reload options.

```APIDOC
### `ignite()` method

```python
app.ignite(
    host="0.0.0.0",   # Bind address
    port=80,           # Port number
    reload=False,      # Enable auto-reload (development)
)
```
```

--------------------------------

### Set up Python development environment

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/contributing.md

Create a virtual environment, activate it, and install the project in editable mode with development dependencies.

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
```

--------------------------------

### Full Tool Call Example in Python

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/guides/tool-calls.md

This comprehensive example demonstrates the complete tool call flow: defining tools, creating an agent, processing LLM streams, executing tool calls, and iterating until a text response is generated. It requires an OpenAI client and LLAMPHouse core components.

```python
from llamphouse.core import Agent
from llamphouse.core.context import Context
from llamphouse.core.streaming.adapters.registry import get_adapter
from openai import AsyncOpenAI
from datetime import datetime, timezone
from typing import Any, Callable, Dict
import json

openai_client = AsyncOpenAI()

# 1. Define your tools
def get_current_time(_: dict[str, Any] | None = None) -> str:
    return datetime.now(timezone.utc).isoformat()

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Return current datetime (UTC) as ISO-8601 string.",
            "parameters": {
                "type": "object",
                "properties": {},
                "additionalProperties": False,
            },
        },
    },
]

TOOL_REGISTRY: Dict[str, Callable] = {
    "get_current_time": get_current_time,
}


# 2. Create an agent with tools
class ToolAgent(Agent):
    def __init__(self):
        super().__init__(id="tool-agent", tools=TOOL_SCHEMAS)

    async def run(self, context: Context):
        messages = [{"role": "system", "content": "You are helpful. Use tools when needed."}]
        for m in context.messages:
            if m.text:
                messages.append({"role": m.role, "content": m.text})

        adapter = get_adapter("openai")

        # 3. Loop: call LLM → handle tool calls → call LLM again
        for _ in range(3):  # max 3 tool call rounds
            stream = await openai_client.chat.completions.create(
                model="gpt-4o-mini",
                messages=messages,
                tools=self.tools,
                tool_choice="auto",
                stream=True,
            )

            full_text = await context.process_stream(stream, adapter)

            # If the LLM produced text, we're done
            if full_text and full_text.strip():
                await context.insert_message(full_text)
                return

            # No text → the LLM requested tool calls
            if not context.pending_tool_calls:
                await context.insert_message("I couldn't process that.")
                return

            # 4. Add the assistant's tool_calls message
            messages.append({
                "role": "assistant",
                "tool_calls": [
                    {
                        "id": tc["id"],
                        "type": "function",
                        "function": {
                            "name": tc["name"],
                            "arguments": tc["arguments"],
                        },
                    }
                    for tc in context.pending_tool_calls
                ],
                "content": None,
            })

            # 5. Execute tools and add results
            for tc in context.pending_tool_calls:
                func_name = tc["name"]
                try:
                    func_args = json.loads(tc["arguments"])
                except (json.JSONDecodeError, TypeError):
                    func_args = {}

                if func_name in TOOL_REGISTRY:
                    result = TOOL_REGISTRY[func_name](func_args)
                else:
                    result = json.dumps({"error": f"Unknown tool: {func_name}"})

                messages.append({
                    "role": "tool",
                    "tool_call_id": tc["id"],
                    "content": str(result),
                })

            # Clear pending calls before next iteration
            context.pending_tool_calls.clear()
```

--------------------------------

### LLAMPHouse Constructor with Adapters

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/adapters.md

Example of how to configure LLAMPHouse with multiple adapters.

```APIDOC
## LLAMPHouse Constructor

### Description
Pass adapters to the `LLAMPHouse` constructor to enable different communication protocols.

### Method
Constructor

### Endpoint
N/A

### Parameters
#### Request Body (Constructor Arguments)
- **agents** (list) - Required - A list of agent objects to be managed by LLAMPHouse.
- **adapters** (list) - Optional - A list of adapter instances to mount. If not specified, `AssistantAPIAdapter` is used by default. If an empty list is provided, no adapters are mounted.
- **compass** (boolean) - Optional - If `False`, the Compass dashboard adapter is not auto-mounted.

### Request Example
```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.adapters.assistant_api import AssistantAPIAdapter

app = LLAMPHouse(
    agents=[...],  # Your list of agents
    adapters=[A2AAdapter(), AssistantAPIAdapter()],
    # data_store=InMemoryDataStore(), # Optional: specify a data store
)
```

### Default Behavior
- If `adapters` is **not specified** (or `None`): `AssistantAPIAdapter` is used by default.
- If `adapters` is an **empty list** (`[]`): no protocol adapters are mounted.
- The **Compass dashboard** adapter is always auto-mounted unless `compass=False`.
```

--------------------------------

### Install LLAMPHouse from PyPI

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/installation.md

Use this command to install the core LLAMPHouse package with all required dependencies from the Python Package Index.

```bash
pip install llamphouse
```

--------------------------------

### Install Dependencies

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/01_HelloWorld/README.md

Install the required Python packages for the project. Ensure you have Python 3.10+.

```sh
pip install -r requirements.txt
```

--------------------------------

### Run Server and Client

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/08_ConfigStore/README.md

Commands to start the agent server and execute the client requests.

```sh
python server.py
```

```sh
python client.py
```

--------------------------------

### Start LLAMPHouse Application

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Start the LLAMPHouse application, specifying the host and port to bind to. Set 'reload' to True for development environments to enable auto-reloading.

```python
app.ignite(
    host="0.0.0.0",   # Bind address
    port=80,           # Port number
    reload=False,      # Enable auto-reload (development)
)
```

--------------------------------

### Verify LLAMPHouse Installation

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/installation.md

Run this command to confirm that LLAMPHouse has been installed successfully by importing it in a Python script.

```python
python -c "import llamphouse; print('LLAMPHouse installed successfully')"
```

--------------------------------

### Using the OpenAI SDK with LLAMPHouse

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/api-compatibility.md

Example of how to configure the OpenAI Python SDK to interact with your LLAMPHouse server.

```APIDOC
```python
from openai import OpenAI

# Point the SDK at your LLAMPHouse server
client = OpenAI(
    base_url="http://127.0.0.1:8000",
    api_key="any",  # or your actual key if auth is enabled
)

# Standard Assistants API usage
thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hello!",
)
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id="my-agent",
)
```
```

--------------------------------

### Define and Run a Simple LLAMPHouse Agent

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/quickstart.md

Create a Python file to define a basic agent with a `run` method and initialize the LLAMPHouse server. This agent inserts a predefined message into the context. The server is then started on localhost.

```python
from llamphouse.core import LLAMPHouse, Agent
from llamphouse.core.context import Context
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.adapters.a2a import A2AAdapter


class HelloAgent(Agent):
    async def run(self, context: Context):
        await context.insert_message(
            "Hello! I'm a simple agent running on LLAMPHouse."
        )


agent = HelloAgent(
    id="hello-agent",
    name="Hello Agent",
    description="A friendly assistant that answers questions.",
    version="0.1.0",
)

app = LLAMPHouse(
    agents=[agent],
    data_store=InMemoryDataStore(),
    adapters=[A2AAdapter()],
)

app.ignite(host="127.0.0.1", port=8000)
```

--------------------------------

### Start local PostgreSQL database

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/contributing.md

Run a PostgreSQL Docker container for local development and create the 'llamphouse' database.

```bash
docker run --rm -d --name postgres \
  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=password \
  -p 5432:5432 postgres
docker exec -it postgres psql -U postgres -c 'CREATE DATABASE llamphouse;'
```

--------------------------------

### Initialize a basic LLAMPHouse agent

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/index.md

Define a simple agent and start the server using the in-memory data store and A2A adapter.

```python
from llamphouse.core import LLAMPHouse, Agent
from llamphouse.core.context import Context
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.adapters.a2a import A2AAdapter


class HelloAgent(Agent):
    async def run(self, context: Context):
        await context.insert_message("Hello from LLAMPHouse!")


app = LLAMPHouse(
    agents=[HelloAgent(id="hello", name="Hello Agent",
                       description="A friendly agent", version="0.1.0")],
    data_store=InMemoryDataStore(),
    adapters=[A2AAdapter()],
)
app.ignite(host="127.0.0.1", port=8000)
```

--------------------------------

### Expected Output for Agent Handover

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/06_AgentHandover/README.md

Example console output demonstrating direct responses versus agent-to-agent handovers.

```text
=== General question (handled directly by Receptionist) ===
  User: What is the capital of Australia?
  Assistant: The capital of Australia is Canberra.

=== Coding question (handed over to Coding Specialist, streamed live) ===
  User: Write a Python function that checks whether a number is prime.
  Assistant: Here's a Python function that checks whether a number is prime:
  ...
```

--------------------------------

### Run the LLAMPHouse Server

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/quickstart.md

Execute the Python script to start the LLAMPHouse server. The agent will be accessible at http://127.0.0.1:8000.

```bash
python server.py
```

--------------------------------

### Register Agents with LLAMPHouse

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/agents.md

Pass a list of your agent instances to the `LLAMPHouse` constructor along with a data store. The `ignite` method then starts the application server.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore

app = LLAMPHouse(
    agents=[agent_a, agent_b, agent_c],
    data_store=InMemoryDataStore(),
)
app.ignite(host="127.0.0.1", port=8000)
```

--------------------------------

### Data Stores

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Explains the available data store options (In-memory and Postgres) and provides examples for their instantiation.

```APIDOC
## Data stores

| Store | Class | When to use |
|---|---|---|
| **In-memory** | `InMemoryDataStore` | Development, testing, stateless deployments |
| **Postgres** | `PostgresDataStore` | Production, persistent data |

```python
# In-memory (default)
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
data_store = InMemoryDataStore()

# Postgres
from llamphouse.core.data_stores.postgres_store import PostgresDataStore
data_store = PostgresDataStore()  # uses DATABASE_URL env var
```
```

--------------------------------

### LLAMPHouse Constructor Configuration

Source: https://context7.com/llamp-ai/llamphouse/llms.txt

Configure the LLAMPHouse server with agents, adapters, data stores, and authentication. The server can be started with or without auto-reloading.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.adapters.assistant_api import AssistantAPIAdapter
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.data_stores.postgres_store import PostgresDataStore
from llamphouse.core.auth.key_auth import KeyAuth

app = LLAMPHouse(
    agents=[agent1, agent2],                  # List of Agent instances
    adapters=[A2AAdapter(), AssistantAPIAdapter()],  # Protocol adapters
    data_store=InMemoryDataStore(),           # Or PostgresDataStore()
    authenticator=KeyAuth("my-secret-key"),   # Optional API key auth
    config_store=None,                        # Optional runtime config store
    retention_policy=None,                    # Optional data retention policy
    exclude_spans=["pattern.*"],              # Optional tracing span exclusions
    compass=True,                             # Enable Compass dashboard (default: True)
)

# Start the server
app.ignite(host="0.0.0.0", port=8000, reload=False)
```

--------------------------------

### Registering Agents

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/agents.md

Provides an example of how to register multiple agents with the LLAMPHouse application.

```APIDOC
## Registering Agents

Pass your agents to the `LLAMPHouse` constructor:

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore

app = LLAMPHouse(
    agents=[agent_a, agent_b, agent_c],
    data_store=InMemoryDataStore(),
)
app.ignite(host="127.0.0.1", port=8000)
```

All registered agents are available via the API and can call each other internally.
```

--------------------------------

### Define Configurable Agent

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/08_ConfigStore/README.md

Example of defining class-level configuration parameters and accessing them within the run method.

```python
class ConfigurableAgent(Agent):
    config = [
        PromptParam(key="system_prompt", label="System Prompt", default="You are a helpful assistant."),
        NumberParam(key="temperature", label="Temperature", default=0.7, min=0, max=2, step=0.1),
        SelectParam(key="tone", label="Tone", default="neutral", options=["neutral", "formal", "casual", "pirate"]),
        BooleanParam(key="verbose", label="Verbose Mode", default=False),
    ]

    async def run(self, context: Context):
        cfg = context.get_config()       # ← resolved defaults + any overrides
        temperature = cfg["temperature"]  # 0.7 (or whatever was set)
        tone = cfg["tone"]                # "neutral" / "pirate" / ...

        # Stream the response
        stream = await openai_client.chat.completions.create(
            messages=messages, model="gpt-4o-mini",
            temperature=temperature, stream=True,
        )
        adapter = get_adapter("openai")
        full_text = await context.process_stream(stream, adapter)
        ...
```

--------------------------------

### Register Multiple Agents with LLAMPHouse

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/multi-agent.md

Initialize LLAMPHouse with a list of agents, a data store, and adapters. The `ignite` method starts the server.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.adapters.a2a import A2AAdapter

app = LLAMPHouse(
    agents=[orchestrator, researcher, writer],
    data_store=InMemoryDataStore(),
    adapters=[A2AAdapter()],
)
app.ignite(host="127.0.0.1", port=8000)
```

--------------------------------

### Docker Compose for Llamphouse Runtime

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/ARCHITECTURE_DRAFT.md

Example of how to use the `llamphouse/runtime` Docker image in `docker-compose.yml` for API and worker services. Demonstrates running the image in different modes by specifying the `command`.

```yaml
# In docker-compose
api:
  image: llamphouse/runtime:latest
  command: ["llamphouse", "serve"]

worker:
  image: llamphouse/runtime:latest
  command: ["llamphouse", "worker"]
  deploy:
    replicas: 3

```

--------------------------------

### Authentication

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Describes how to implement custom authentication using `BaseAuth` and provides an example using `KeyAuth`, including the required header format.

```APIDOC
## Authentication

Implement `BaseAuth` for custom authentication:

```python
from llamphouse.core.auth.key_auth import KeyAuth

app = LLAMPHouse(
    agents=[...],
    authenticator=KeyAuth("my-secret-key"),
)
```

Clients must include the key in the `Authorization` header:

```
Authorization: Bearer my-secret-key
```
```

--------------------------------

### Interact with LLAMPHouse Agent using OpenAI SDK

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/getting-started/quickstart.md

Utilize the `openai` Python SDK to communicate with the LLAMPHouse agent by setting the `base_url` to the server's address. This demonstrates creating a thread, sending a message, and starting a run programmatically.

```python
from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8000", api_key="any")

thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id, role="user", content="Hello!"
)
run = client.beta.threads.runs.create(
    thread_id=thread.id, assistant_id="hello-agent"
)
```

--------------------------------

### Define Tool Schemas for Function Calling

Source: https://context7.com/llamp-ai/llamphouse/llms.txt

Define tool schemas and a registry for function calling. The LLM can then decide when to call these tools, execute them, and feed the results back. This example defines a tool to get the current time.

```python
from llamphouse.core import LLAMPHouse, Agent
from llamphouse.core.context import Context
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.streaming.adapters.registry import get_adapter
from llamphouse.core.types.run import ToolOutput
from openai import AsyncOpenAI
from datetime import datetime, timezone
import json

openai_client = AsyncOpenAI()

# 1. Define tool schemas and registry
def get_current_time(_: dict = None) -> str:
    return datetime.now(timezone.utc).isoformat()

TOOL_SCHEMAS = [
    {
        "type": "function",
        "function": {
            "name": "get_current_time",
            "description": "Return current datetime (UTC) as ISO-8601 string.",
            "parameters": {"type": "object", "properties": {}, "additionalProperties": False},
        },
    },
]

TOOL_REGISTRY = {"get_current_time": get_current_time}
```

--------------------------------

### LLAMPHouse Constructor and Parameters

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Demonstrates how to initialize the LLAMPHouse class with various configuration options and provides a reference for each parameter.

```APIDOC
## LLAMPHouse Constructor

The `LLAMPHouse` class accepts the following parameters:

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.adapters.assistant_api import AssistantAPIAdapter
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.data_stores.postgres_store import PostgresDataStore

app = LLAMPHouse(
    agents=[...],                        # List of Agent instances
    adapters=[A2AAdapter()],             # Protocol adapters
    data_store=InMemoryDataStore(),      # Storage backend
    authenticator=None,                  # Optional authentication
    worker=None,                         # Optional custom worker
    event_queue_class=None,              # Event queue implementation
    run_queue=None,                      # Run queue implementation
    config_store=None,                   # Runtime config store
    retention_policy=None,               # Data retention policy
    exclude_spans=None,                  # Tracing span exclusions
    compass=True,                        # Enable Compass dashboard
)
```

### Parameter Reference

| Parameter | Type | Default | Description |
|---|---|---|---|
| `agents` | `list[Agent]` | `[]` | List of agent instances to register |
| `adapters` | `list[BaseAPIAdapter]` | `[AssistantAPIAdapter()]` | Protocol adapters. `None` → default; `[]` → none |
| `data_store` | `BaseDataStore` | `InMemoryDataStore()` | Storage backend for threads, messages, runs |
| `authenticator` | `BaseAuth` | `None` | Authentication handler |
| `worker` | `BaseWorker` | `None` | Custom worker implementation |
| `event_queue_class` | `BaseEventQueue` | `InMemoryEventQueue` | Event queue class for streaming |
| `run_queue` | `BaseQueue` | `InMemoryQueue()` | Queue for pending runs |
| `config_store` | `BaseConfigStore` | `InMemoryConfigStore()` | Runtime config parameter store |
| `retention_policy` | `RetentionPolicy` | Default policy | Data retention/purge configuration |
| `exclude_spans` | `list[str]` | `[]` | Glob patterns for spans to exclude from tracing |
| `compass` | `bool` | `True` | Auto-mount the Compass dashboard adapter |
```

--------------------------------

### Configure Environment Variables

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/04_ToolCall/README.md

Creates the .env file from the provided sample template.

```bash
cp .env.sample .env
```

--------------------------------

### Build the project

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/contributing.md

Build the project package using the 'build' tool.

```bash
python -m build
```

--------------------------------

### Query Full-Text Search

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/ARCHITECTURE_DRAFT.md

Example query for performing ranked keyword searches against the messages table.

```sql
SELECT m.*, ts_rank(search_vec, q) AS rank
FROM   messages m, plainto_tsquery('english', :query) q
WHERE  search_vec @@ q
ORDER  BY rank DESC
LIMIT  50;
```

--------------------------------

### Configure Data Stores

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Instantiate either InMemoryDataStore for development/testing or PostgresDataStore for production. PostgresDataStore uses the DATABASE_URL environment variable.

```python
# In-memory (default)
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
data_store = InMemoryDataStore()

# Postgres
from llamphouse.core.data_stores.postgres_store import PostgresDataStore
data_store = PostgresDataStore()  # uses DATABASE_URL env var
```

--------------------------------

### Run all tests

Source: https://github.com/llamp-ai/llamphouse/blob/main/tests/README.md

Execute the entire test suite from the repository root.

```bash
python -m pytest
```

--------------------------------

### Configure Postgres Full-Text Search

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/ARCHITECTURE_DRAFT.md

Setup for keyword search using a tsvector column and GIN index on the messages table.

```sql
-- Add a tsvector column + GIN index to the messages table
ALTER TABLE messages ADD COLUMN search_vec tsvector
    GENERATED ALWAYS AS (to_tsvector('english', coalesce(content_text, ''))) STORED;

CREATE INDEX idx_messages_search ON messages USING GIN(search_vec);
```

--------------------------------

### Initialize LLAMPHouse with Redis Queues

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/deployment.md

Configure LLAMPHouse to use Redis for run and event queues, essential for multi-process deployments and scalability. Requires `REDIS_URL` to be set.

```python
from llamphouse.core.queues.redis_queue import RedisQueue
from llamphouse.core.streaming.event_queue.redis_event_queue import RedisEventQueue

app = LLAMPHouse(
    agents=[...],
    run_queue=RedisQueue(),               # reads REDIS_URL
    event_queue_class=RedisEventQueue,    # reads REDIS_URL
)
```

--------------------------------

### Run Automated Comparison

Source: https://github.com/llamp-ai/llamphouse/blob/main/examples/10_DistributedWorker/README.md

Execute the client to automatically compare both server modes.

```bash
python client.py               # 10 concurrent runs (default)
python client.py --runs 20     # more runs
```

--------------------------------

### Create a feature branch

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/contributing.md

Start a new feature branch from the main branch using Git. Replace amazing-feature with your feature's name.

```bash
git checkout -b feature/amazing-feature
```

--------------------------------

### Defining an Agent

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/agents.md

Demonstrates how to create a basic agent by subclassing the `Agent` class and implementing the `run()` method.

```APIDOC
## Defining an Agent

An **Agent** is the core building block in LLAMPHouse. It's a Python class that subclasses `Agent` and implements a `run()` method — this is where your logic lives.

```python
from llamphouse.core import Agent
from llamphouse.core.context import Context


class MyAgent(Agent):
    async def run(self, context: Context):
        # Your agent logic here
        await context.insert_message("Hello!")
```

The `run()` method is called whenever a run is created for this agent. It receives a [Context](context.md) object with the full conversation history and a toolkit for sending replies, streaming, calling other agents, and more.
```

--------------------------------

### Production Docker Compose for Single Machine

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/ARCHITECTURE_DRAFT.md

Optimized for production on a single machine, this setup separates the API and worker services for independent scaling.

```yaml
# docker-compose.prod.yml
services:
  api:                  # llamphouse/runtime — `llamphouse serve`
  worker:               # llamphouse/runtime — `llamphouse worker`
    replicas: 3         # scale workers independently
  spotlight:            # llamphouse/spotlight
  compass:              # llamphouse/compass
  postgres:
  redis:
  clickhouse:
  otel-collector:
```

--------------------------------

### Call Agent and Transform Output Chunks

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/multi-agent.md

Use `context.call_agent()` to invoke another agent and modify each output chunk before sending it to the client, for example, by converting it to uppercase.

```python
async for chunk in await context.call_agent("agent-b", "Do something"):
    context.send_chunk(chunk.upper())
```

--------------------------------

### Initialize LLAMPHouse Constructor

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/configuration.md

Instantiate the LLAMPHouse class with various components like agents, adapters, and data stores. The 'compass' parameter enables the Compass dashboard.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.adapters.assistant_api import AssistantAPIAdapter
from llamphouse.core.data_stores.in_memory_store import InMemoryDataStore
from llamphouse.core.data_stores.postgres_store import PostgresDataStore

app = LLAMPHouse(
    agents=[...],                        # List of Agent instances
    adapters=[A2AAdapter()],             # Protocol adapters
    data_store=InMemoryDataStore(),      # Storage backend
    authenticator=None,                  # Optional authentication
    worker=None,                         # Optional custom worker
    event_queue_class=None,              # Event queue implementation
    run_queue=None,                      # Run queue implementation
    config_store=None,                   # Runtime config store
    retention_policy=None,               # Data retention policy
    exclude_spans=None,                  # Tracing span exclusions
    compass=True,                        # Enable Compass dashboard
)
```

--------------------------------

### Docker Compose for Tracing Pipeline

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/guides/tracing.md

The Docker Compose configuration includes components for the OpenTelemetry Collector and ClickHouse, essential for the tracing pipeline. Start the services in detached mode.

```yaml
# docker/docker-compose.yml includes:
# - OTel Collector (port 4318)
# - ClickHouse (port 8123)
```

--------------------------------

### Deploy with Docker Compose

Source: https://context7.com/llamp-ai/llamphouse/llms.txt

Commands and configuration for deploying the runtime environment with supporting services.

```bash
cd docker
docker compose up -d
```

```yaml
# docker/docker-compose.yml
services:
  runtime:
    build: ./runtime
    ports:
      - "8080:8080"
    environment:
      DATABASE_URL: postgresql+asyncpg://postgres:password@postgres:5432/llamphouse
      REDIS_URL: redis://redis:6379
      LLAMPHOUSE_TRACING_ENABLED: "true"
      OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318
      OTEL_SERVICE_NAME: llamphouse
      CLICKHOUSE_URL: http://clickhouse:8123
    depends_on:
      - postgres
      - redis

  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: llamphouse
    ports:
      - "5432:5432"

  redis:
    image: redis:7
    ports:
      - "6379:6379"

  otel-collector:
    image: otel/opentelemetry-collector
    ports:
      - "4318:4318"

  clickhouse:
    image: clickhouse/clickhouse-server
    ports:
      - "8123:8123"
```

--------------------------------

### Run all tests

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/contributing.md

Execute all unit, contract, and integration tests for the project. Use the -v flag for verbose output.

```bash
python -m pytest tests/ -v
```

--------------------------------

### LLAMPHouse API Server Configuration

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/deployment.md

Configuration for the LLAMPHouse API server in a split-mode deployment. This setup handles HTTP requests and relies on external services for data and queues.

```python
# api.py — API server only (no worker)
app = LLAMPHouse(
    agents=[...],
    data_store=PostgresDataStore(),
    run_queue=RedisQueue(),
    event_queue_class=RedisEventQueue,
)
# Start with: python -m llamphouse --no-workers api.py
```

--------------------------------

### Call another agent and forward response chunks

Source: https://github.com/llamp-ai/llamphouse/blob/main/README.md

Use this pattern to delegate a task to another agent and process its response incrementally. No specific setup is required beyond having the target agent available.

```python
async for chunk in await context.call_agent("researcher", "Find info about X"):
    context.send_chunk(chunk)
```

--------------------------------

### Configure Config Store Backend

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/guides/config-store.md

Specify a persistent config store backend when initializing the LLAMPHouse application to maintain values across restarts.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.config_stores.in_memory import InMemoryConfigStore

app = LLAMPHouse(
    agents=[...],
    config_store=InMemoryConfigStore(),  # default
)
```

--------------------------------

### Configure LLAMPHouse with adapters

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/adapters.md

Pass a list of adapter instances to the LLAMPHouse constructor to enable specific communication protocols.

```python
from llamphouse.core import LLAMPHouse
from llamphouse.core.adapters.a2a import A2AAdapter
from llamphouse.core.adapters.assistant_api import AssistantAPIAdapter

app = LLAMPHouse(
    agents=[...],
    adapters=[A2AAdapter(), AssistantAPIAdapter()],
)
```

--------------------------------

### Initialize LLAMPHouse with Postgres Data Store

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/deployment.md

Configure LLAMPHouse to use PostgreSQL for persistent data storage. This requires the `DATABASE_URL` environment variable to be set.

```python
from llamphouse.core.data_stores.postgres_store import PostgresDataStore

app = LLAMPHouse(
    agents=[...],
    data_store=PostgresDataStore(),  # reads DATABASE_URL
)
```

--------------------------------

### Create Run with cURL

Source: https://github.com/llamp-ai/llamphouse/blob/main/README.md

Initiate a run for an assistant on a specific thread. Ensure the `assistant_id` matches an agent defined in your server.

```bash
curl -s -X POST "http://127.0.0.1:8000/threads/$THREAD_ID/runs" \
  -H "Content-Type: application/json" \
  -d '{"assistant_id": "hello-agent"}'
```

--------------------------------

### Instantiate an Agent with Identity Parameters

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/concepts/agents.md

When creating an agent instance, provide essential identity parameters like `id`, `name`, `description`, `version`, and `skills`. The `id` is required for routing.

```python
agent = MyAgent(
    id="my-agent",           # Unique identifier (required)
    name="My Agent",         # Human-readable name
    description="An agent.", # Description shown in agent cards
    version="0.1.0",         # Version string
    skills=["chat", "math"], # Skill tags for A2A discovery
)
```

--------------------------------

### LLAMPHouse Constructor Configuration

Source: https://github.com/llamp-ai/llamphouse/blob/main/README.md

Configure the LLAMPHouse instance with various components like agents, adapters, data stores, and authentication. Defaults are provided for most parameters.

```python
LLAMPHouse(
    agents=[...],                  # List of Agent instances
    adapters=[A2AAdapter()],       # Protocol adapters (default: AssistantAPIAdapter)
    data_store=InMemoryDataStore(),# In-memory (default) or PostgresDataStore
    authenticator=KeyAuth("key"),  # Optional API key auth
    config_store=None,             # Optional runtime config store
    retention_policy=None,         # Optional data retention/purge policy
    exclude_spans=["pattern.*"],   # Optional tracing span exclusions
    compass=True,                  # Enable/disable Compass dashboard (default: True)
)
```

--------------------------------

### Configure LLAMPHouse Environment Variables

Source: https://context7.com/llamp-ai/llamphouse/llms.txt

Set these environment variables to configure database connections, Redis queues, and OpenTelemetry tracing.

```bash
# Database (Postgres)
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/llamphouse

# Redis (for distributed queues)
REDIS_URL=redis://localhost:6379

# Tracing
LLAMPHOUSE_TRACING_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
OTEL_SERVICE_NAME=llamphouse

# Compass dashboard trace storage
CLICKHOUSE_URL=http://localhost:8123
```

--------------------------------

### Interact with LLAMPHouse using OpenAI SDK

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/api-compatibility.md

Configure the OpenAI Python SDK to point to your LLAMPHouse server and perform standard Assistants API operations like creating threads, adding messages, and creating runs. Ensure the `base_url` is set to your LLAMPHouse instance.

```python
from openai import OpenAI

# Point the SDK at your LLAMPHouse server
client = OpenAI(
    base_url="http://127.0.0.1:8000",
    api_key="any",  # or your actual key if auth is enabled
)

# Standard Assistants API usage
thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Hello!",
)
run = client.beta.threads.runs.create(
    thread_id=thread.id,
    assistant_id="my-agent",
)
```

--------------------------------

### Implement basic streaming agent

Source: https://github.com/llamp-ai/llamphouse/blob/main/docs/guides/streaming.md

Use context.process_stream with a provider-specific adapter to forward tokens to the client in real time.

```python
from openai import AsyncOpenAI
from llamphouse.core import Agent
from llamphouse.core.context import Context
from llamphouse.core.streaming.adapters.registry import get_adapter

openai_client = AsyncOpenAI()


class StreamingAgent(Agent):
    async def run(self, context: Context):
        # Optional: send a status event while preparing
        context.emit("status", {"message": "Calling OpenAI..."})

        # Build conversation history
        messages = [
            {"role": m.role, "content": m.text}
            for m in context.messages
        ]

        # Start streaming from OpenAI
        stream = await openai_client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
            stream=True,
        )

        # Pipe through LLAMPHouse — tokens forwarded to client in real time
        adapter = get_adapter("openai")
        full_text = await context.process_stream(stream, adapter)

        # Persist the complete response
        if full_text and full_text.strip():
            await context.insert_message(full_text)
```