Directives

The Directive Engine preprocesses prompts before the LLM call, resolving @context, @memory, @agent, /tool, /mcp, and #meta directives into enriched context. This enables small and local models to leverage the full Sagewai infrastructure without native tool-calling support.

from sagewai import DirectiveEngine

engine = DirectiveEngine(
    context=my_context_engine,
    model="codellama:7b",
)
result = await engine.resolve("@context('ML basics') Help me learn")
# result.prompt contains enriched text with context injected

DirectiveEngine

Main orchestrator for prompt preprocessing. Supports two syntax modes:

• Sigil mode (resolve): @context('q'), /tool.name('a'), #model:x
• Template mode (resolve_template): {{ context.search('q') }}

Both modes resolve through the same pipeline: parse, resolve, format, compress, and assemble.

from sagewai import DirectiveEngine

engine = DirectiveEngine(
    context=context_engine,
    memory=memory_provider,
    tools={"search": search_tool},
    agents={"researcher": researcher_agent},
    model="gpt-4o",
    resolution_timeout=10.0,
)
result = await engine.resolve(
    "@context('machine learning') @memory('previous findings') Summarize"
)

Constructor

Methods

DirectiveResult

Result of directive resolution. Contains the enriched prompt and metadata.

result = await engine.resolve("@context('topic') My question")

print(result.prompt)           # Enriched prompt with context injected
print(result.clean_prompt)     # Original text with directives stripped
print(result.context_blocks)   # Resolved context blocks
print(result.metadata)         # Token counts, timings, stats
print(result.tool_descriptions)  # Tool descriptions for prompt-based calling

Fields

ModelProfile

Defines how the Directive Engine formats output for a model class. Controls compression aggressiveness, delimiter style, tool-call mode, and token budget allocation.

from sagewai import ModelProfile

profile = ModelProfile(
    name="custom",
    max_context_tokens=8192,
    compression_ratio=2.0,
    tool_call_mode="prompt_based",
)

Fields

Built-in Profiles

detect_profile

Auto-detect the model profile from a model name string. Matches against known patterns and falls back to MEDIUM for unknown models.

from sagewai import detect_profile

profile = detect_profile("codellama:7b-instruct")  # -> SMALL
profile = detect_profile("gpt-4o")                  # -> LARGE
profile = detect_profile("ollama/mistral")           # -> SMALL
profile = detect_profile("unknown-model")            # -> MEDIUM

Signature

detect_profile(model: str) -> ModelProfile

Directive Syntax Reference