Model-Family Harness

The model-family harness picks a small system-prompt fragment and the preferred file-edit tool that suit the model you’re using — set no config to keep today’s behaviour, or opt in by naming a supported model.

from praisonaiagents import Agent

# Claude family → harness prepends patch-first guidance,
# coding toolset advertises apply_patch before edit_file.
agent = Agent(
    name="coder",
    llm="claude-opus-4",
    toolsets=["coding"],
)
agent.start("Refactor UserService to AccountService across src/")

The agent sets llm="claude-opus-4"; the harness resolves the anthropic profile and shapes both the system prompt and the coding toolset automatically.

Unknown or non-string model ids resolve to the default profile — the system prompt and toolset order stay byte-for-byte identical to earlier versions. Adopting the harness requires no config change.

Quick Start

Zero config (default profile — behaviour unchanged)

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Write Python.",
)
agent.start("Write a hello-world script")

Opt in — Anthropic family

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Edit files in this repo.",
    llm="claude-opus-4",
    toolsets=["coding"],
)
agent.start("Rename `run_all` to `run_pipeline` in src/")

On this agent, apply_patch is advertised before edit_file, and the system prompt gains: “When editing files, prefer patch-style edits: use apply_patch to create or rewrite files and edit_file for targeted changes.”

Opt in — OpenAI family

from praisonaiagents import Agent

agent = Agent(
    name="Coder",
    instructions="Edit files in this repo.",
    llm="gpt-4o",
    toolsets=["coding"],
)

Here edit_file is advertised first, with a matching prompt fragment.

Inspect the resolved profile

from praisonaiagents import resolve_harness

profile = resolve_harness("claude-opus-4")
print(profile.name)                    # "anthropic"
print(profile.preferred_edit_format)   # "apply_patch"
print(profile.base_prompt)             # "When editing files, prefer patch-style edits: …"

profile = resolve_harness("gpt-4o")
print(profile.name)                    # "openai"
print(profile.preferred_edit_format)   # "edit_file"

profile = resolve_harness("mistral-large")
print(profile.name)                    # "default" (unknown → behaviour-preserving)

from praisonaiagents import HarnessProfile, register_profile

register_profile(
    ["my-open-model", "myco/"],
    HarnessProfile(
        name="my_family",
        base_prompt="When editing files, always use apply_patch.",
        preferred_edit_format="apply_patch",
    ),
)

Override on a single agent

from praisonaiagents import Agent

agent = Agent(name="coder", llm="claude-opus-4", toolsets=["coding"])
agent.harness_base_prompt = ""   # disable the fragment for this agent only

How It Works

The agent resolves a profile from the model id at prompt-build time, then prepends the fragment and reorders the edit tools.

Step	What happens
`Agent.__init__`	Reads `self.llm` (only when it’s a `str`) and calls `resolve_toolsets_for_model(toolsets, model_id)` to reorder edit primitives.
`_build_system_prompt`	Calls `_resolve_harness_base_prompt()`; if the profile has a `base_prompt`, it’s prepended as `f"{harness_prompt}\n\n{system_prompt}"`.
Override	An explicit `harness_base_prompt` attribute on the Agent wins over resolver output. Any error path collapses to no fragment (default profile).
Fallback	Falsy, unknown, or object-based model ids → default profile, no change

Which override do I need?

Precedence

Resolution follows a fixed order, from most specific to the behaviour-preserving fallback:

Agent.harness_base_prompt (explicit override) > register_profile(...) (user-registered, most recent wins) > built-in matchers (anthropic, openai) > DEFAULT_PROFILE

Configuration Options

Import the harness API from the top level (all lazy — no import-time cost):

from praisonaiagents import HarnessProfile, resolve_harness, register_profile

Or from the submodule for the full surface:

from praisonaiagents.model_harness import (
    HarnessProfile,
    HarnessResolverProtocol,
    resolve_harness,
    register_profile,
    DEFAULT_PROFILE,
)

`HarnessProfile` fields

Field	Type	Default	Description
`name`	`str`	`"default"`	Profile identifier (e.g. `"default"`, `"anthropic"`, `"openai"`)
`base_prompt`	`Optional[str]`	`None`	Prompt fragment prepended to the system prompt. `None` = no fragment (behaviour-preserving)
`preferred_edit_format`	`Optional[str]`	`None`	Preferred edit primitive — `"apply_patch"` or `"edit_file"`. `None` = keep exposing both primitives in their current order

Built-in registry

First match wins; matching is case-insensitive substring on the model id.

Match substrings (case-insensitive)	Profile name	`base_prompt`	`preferred_edit_format`
`claude`, `anthropic`	`anthropic`	”When editing files, prefer patch-style edits: use apply_patch to create or rewrite files and edit_file for targeted changes.”	`apply_patch`
`gpt`, `openai`, `o1`, `o3`, `o4`	`openai`	”When editing files, prefer targeted string-replacement edits: use edit_file to modify existing files precisely.”	`edit_file`
(no match / falsy id)	`default`	`None`	`None`

Functions

Function	Signature	Behaviour
`resolve_harness`	`resolve_harness(model: Optional[str]) -> HarnessProfile`	Case-insensitive substring match, first match wins. Falsy or unknown model → `DEFAULT_PROFILE`
`register_profile`	`register_profile(matchers: List[str], profile: HarnessProfile) -> None`	Prepends a `(matchers, profile)` mapping so caller profiles take precedence. Process-global and thread-safe

Toolset helpers for advanced users composing custom coding toolsets:

from praisonaiagents import resolve_toolsets_for_model
from praisonaiagents.toolsets import (
    ToolsetRegistry,  # .resolve_toolset_for_model / .resolve_toolsets_for_model
    resolve_toolsets_for_model,
)

Common Patterns

Pass the model id and the resolver does the rest — no extra configuration required.

All-Claude team — do nothing; naming a claude-… model activates the profile automatically.
Mixed models via a router — leave llm unset per agent and pass the model id per call. The resolver reads self.llm at prompt build-time, so a mid-run model swap picks up the new profile each turn.

Local Ollama model treated like Claude — register a profile at startup:

from praisonaiagents import HarnessProfile, register_profile

register_profile(
    ["ollama/my-coder"],
    HarnessProfile(
        name="my",
        preferred_edit_format="apply_patch",
        base_prompt="Prefer patch-style edits.",
    ),
)

Team on Llama or Mistral — register once at startup so every downstream agent gets the family hint:

from praisonaiagents import HarnessProfile, register_profile

register_profile(
    ["llama", "mistral"],
    HarnessProfile(name="open-weights", preferred_edit_format="edit_file"),
)

Strip the auto fragment on one agent — set agent.harness_base_prompt = "".

Add a house-style opener for every model

from praisonaiagents import HarnessProfile, register_profile

register_profile(
    ["gpt", "claude", "gemini", "llama"],
    HarnessProfile(
        name="house_style",
        base_prompt="Follow the team style guide. Keep diffs small.",
    ),
)

YAML usage

Nothing new to configure — the harness reads the llm field on the agent block, so YAML paths get the improvement automatically:

agents:
  coder:
    role: Coding Assistant
    llm: claude-opus-4      # → anthropic profile picked up automatically
    toolsets: [coding]

CLI usage

No new flag — praisonai run picks up the profile from the model id:

praisonai run "Refactor src/" --toolset coding --model claude-opus-4

End-to-end examples

from praisonaiagents import Agent, resolve_harness, register_profile, HarnessProfile

# 1) Default behaviour — no model id set → default profile, unchanged.
Agent(name="a1", toolsets=["coding"])

# 2) Claude family — patch-first harness, apply_patch advertised first.
Agent(name="a2", llm="claude-opus-4", toolsets=["coding"])

# 3) GPT family — replace-first harness, edit_file advertised first.
Agent(name="a3", llm="gpt-4o", toolsets=["coding"])

# 4) Inspect the resolver.
resolve_harness("claude-opus-4").preferred_edit_format   # "apply_patch"
resolve_harness("gpt-4o").preferred_edit_format          # "edit_file"
resolve_harness("some-unknown").preferred_edit_format    # None

# 5) Register a custom family.
register_profile(
    ["my-open-model"],
    HarnessProfile(name="my_family",
                   base_prompt="Prefer apply_patch for all edits.",
                   preferred_edit_format="apply_patch"),
)

# 6) Per-agent opt-out.
agent = Agent(name="a4", llm="claude-opus-4", toolsets=["coding"])
agent.harness_base_prompt = ""

User Interaction Flow

A user creates an Agent(llm="claude-opus-4", toolsets=["coding"]) and types "Refactor src/user.py". The harness resolver sees "claude-opus-4", picks the anthropic profile, prepends the patch-first guidance to the agent’s system prompt, and advertises apply_patch before edit_file in the coding toolset. The agent reaches for apply_patch first — no config touched. The same user later switches to llm="gpt-4o". Same code, same toolset — the resolver now picks the openai profile, and the agent reaches for edit_file first. Still no config touched.

Best Practices

Trust the default. Ship first, tune later.

The default profile is byte-for-byte identical to pre-harness behaviour — verified by test_coding_toolset_unknown_model_is_byte_for_byte. Recognised families gain tuned guidance automatically; everything else stays the same.

The registry is process-global. Call register_profile once during application startup — registering inside request handlers repeatedly prepends duplicate mappings.

def setup_harness():
    register_profile(["my-open-model"], HarnessProfile(name="my_family"))

Match on stable substrings.

Matchers are case-insensitive substring hits against the model id, first match wins. Keep them short and stable — "claude", "gpt" — so new model versions in the same family match without edits. Registrations prepend, so a custom mapping overrides the built-in defaults.

Don't rely on tool ordering being enforced.

Both edit primitives remain available; the model can still call the non-preferred one. Ordering is a hint, not a constraint.

Pass the model id as a string when you want the harness on.

Object-based LLMs resolve to the default profile by design, so custom LLM wrappers don’t silently pick up an unrelated family’s guidance. Pass a string llm= model id to opt in.

Backward compatibility: Default behaviour is unchanged. Agents that don’t set a supported llm string, don’t set toolsets, or use a non-string LLM object continue producing byte-for-byte identical system prompts and tool orderings.

Toolsets

The coding toolset whose edit-primitive order the harness reorders.

File Editing

The edit_file and apply_patch primitives themselves

Rules

The other lever that shapes the assembled system prompt

Prompt Cache Optimization

The fragment is prepended, so it participates in cache-key ordering

Models

The model id you pass is the trigger for profile resolution.

​Quick Start

​How It Works

​Which override do I need?

​Precedence

​Configuration Options

​HarnessProfile fields

​Built-in registry

​Functions

​Common Patterns

​Add a house-style opener for every model

​YAML usage

​CLI usage

​End-to-end examples

​User Interaction Flow

​Best Practices

​Related

Toolsets

File Editing

Rules

Prompt Cache Optimization

Models

Quick Start

How It Works

Which override do I need?

Precedence

Configuration Options

`HarnessProfile` fields

Built-in registry

Functions

Common Patterns

Add a house-style opener for every model

YAML usage

CLI usage

End-to-end examples

User Interaction Flow

Best Practices

Related