Freehold Agent

Layer 2: Local AI agent for Personal Context Infrastructure.

Overview

The Freehold Agent provides:

• Local AI Processing - Run language models on your device
• Context Retrieval - Query encrypted context store
• Policy Enforcement - Validate requests against S-PAL policies
• Decision Support - AI-powered assistance without data leakage

Installation

# Clone and install
git clone https://github.com/freehold-earth/freehold.git
cd freehold/agent
uv sync

# With LLM support (llama-cpp-python)
uv sync --extra llm

Quick Start

from freehold_agent import Agent, AgentConfig

# Initialize agent
agent = Agent(
    AgentConfig(
        model_path="models/phi-3-mini-q4.gguf",
    )
)

# Process a request with policy enforcement
response = await agent.process(
    query="What are my upcoming appointments?",
    policy_id="calendar-access",
)

print(response.content)

Architecture

flowchart TB
    subgraph Agent["Freehold Agent"]
        QH["Query Handler"]
        QH --> PC["Policy Checker"]
        QH --> CR["Context Retriever"]
        QH --> LLM["LLM Inference"]
    end

    PC --> SPAL["S-PAL Policy"]
    CR --> CS["Context Store"]

Supported Models

The agent works with GGUF-format models:

Local Inference

Two backends are supported behind a single protocol:

• Ollama (recommended) — talks HTTP to a local ollama serve daemon (default http://127.0.0.1:11434). Cross-platform, transparent MLX on Apple Silicon, and supports JSON-schema constrained output via Ollama's format parameter — used by the S-PAL flow to synthesise validated RequestContext proposals.
• llama-cpp-python (in-process, "no daemon") — kept as a fallback for single-executable demos. Requires the optional llm extra: uv sync --extra llm.

Named model tiers (Ollama backend):

freehold-agent targets desktop and server runtimes; the mobile / on-device story lives in a separate native client (see ADR-006 in pci-docs). This release does not expose an on-device tier — Bonsai-27B and similar Q1_0 models depend on llama.cpp backend support that isn't yet wired into every Ollama build (see ollama/ollama#15359 for tracking).

Basic usage:

from freehold_agent import Agent, AgentConfig, LLMConfig

agent = Agent(AgentConfig(llm=LLMConfig(backend="ollama", ollama_tier="default")))
await agent.initialize()
try:
    # S-PAL wiring: synthesise a RequestContext for the policy checker
    request_ctx = await agent.propose_request_context(
        "Business wants age >= 18 verification for alcohol purchase."
    )
finally:
    await agent.close()

Integration smoke tests against a live Ollama daemon:

ollama pull phi4-mini:3.8b
PCI_OLLAMA_MODEL=phi4-mini:3.8b uv run pytest -m ollama

Environment Variables

Development

# Install with dev dependencies
uv sync --group dev

# Run tests
uv run pytest

# Type check
uv run mypy src/

# Lint
uv run ruff check src/

# Run the agent
uv run python -m freehold_agent

Related Packages

• pci-spec - S-PAL schema and protocols
• pci-context-store - Layer 1: Context Store
• pci-contracts - Layer 3: Smart Contracts
• pci-zkp - Layer 4: Zero-Knowledge Proofs
• pci-identity - Layer 5: DID Management

License

Apache 2.0