Skip to content

sys_prompts

Class info

Classes

Name Children Inherits
SystemPrompts
llmling_agent.agent.sys_prompts
Manages system prompts for an agent.

    🛈 DocStrings

    System prompt management.

    SystemPrompts

    Manages system prompts for an agent.

    Source code in src/llmling_agent/agent/sys_prompts.py 
     55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    class SystemPrompts:
    """Manages system prompts for an agent."""

    def __init__(
        self,
        prompts: AnyPromptType | list[AnyPromptType] | None = None,
        template: str | None = None,
        dynamic: bool = True,
        context: AgentContext | None = None,
        inject_agent_info: bool = True,
        inject_tools: ToolInjectionMode = "off",
        tool_usage_style: ToolUsageStyle = "suggestive",
    ):
        """Initialize prompt manager."""
        from jinjarope import Environment
        from toprompt import to_prompt

        match prompts:
            case list():
                self.prompts = prompts
            case None:
                self.prompts = []
            case _:
                self.prompts = [prompts]
        self.context = context
        self.template = template
        self.dynamic = dynamic
        self.inject_agent_info = inject_agent_info
        self.inject_tools = inject_tools
        self.tool_usage_style = tool_usage_style
        self._cached = False
        self._env = Environment(enable_async=True)
        self._env.filters["to_prompt"] = to_prompt

    def __repr__(self) -> str:
        return (
            f"SystemPrompts(prompts={len(self.prompts)}, "
            f"dynamic={self.dynamic}, inject_agent_info={self.inject_agent_info}, "
            f"inject_tools={self.inject_tools!r})"
        )

    def __len__(self) -> int:
        return len(self.prompts)

    def __getitem__(self, idx: int | slice) -> AnyPromptType | list[AnyPromptType]:
        return self.prompts[idx]

    async def add_by_reference(self, reference: str):
        """Add a system prompt using reference syntax.

        Args:
            reference: [provider:]identifier[@version][?var1=val1,...]

        Examples:
            await sys_prompts.add_by_reference("code_review?language=python")
            await sys_prompts.add_by_reference("langfuse:expert@v2")
        """
        if not self.context:
            msg = "No context available to resolve prompts"
            raise RuntimeError(msg)

        try:
            content = await self.context.prompt_manager.get(reference)
            self.prompts.append(content)
        except Exception as e:
            msg = f"Failed to add prompt {reference!r}"
            raise RuntimeError(msg) from e

    async def add(
        self,
        identifier: str,
        *,
        provider: str | None = None,
        version: str | None = None,
        variables: dict[str, Any] | None = None,
    ):
        """Add a system prompt using explicit parameters.

        Args:
            identifier: Prompt identifier/name
            provider: Provider name (None = builtin)
            version: Optional version string
            variables: Optional template variables

        Examples:
            await sys_prompts.add("code_review", variables={"language": "python"})
            await sys_prompts.add("expert", provider="langfuse", version="v2")
        """
        if not self.context:
            msg = "No context available to resolve prompts"
            raise RuntimeError(msg)

        try:
            content = await self.context.prompt_manager.get_from(
                identifier,
                provider=provider,
                version=version,
                variables=variables,
            )
            self.prompts.append(content)
        except Exception as e:
            ref = f"{provider + ':' if provider else ''}{identifier}"
            msg = f"Failed to add prompt {ref!r}"
            raise RuntimeError(msg) from e

    def clear(self):
        """Clear all system prompts."""
        self.prompts = []

    async def refresh_cache(self):
        """Force re-evaluation of prompts."""
        from toprompt import to_prompt

        evaluated = []
        for prompt in self.prompts:
            result = await to_prompt(prompt)
            evaluated.append(result)
        self.prompts = evaluated
        self._cached = True

    @asynccontextmanager
    async def temporary_prompt(
        self, prompt: AnyPromptType, exclusive: bool = False
    ) -> AsyncIterator[None]:
        """Temporarily override system prompts.

        Args:
            prompt: Single prompt or sequence of prompts to use temporarily
            exclusive: Whether to only use given prompt. If False, prompt will be
                       appended to the agents prompts temporarily.
        """
        from toprompt import to_prompt

        original_prompts = self.prompts.copy()
        new_prompt = await to_prompt(prompt)
        self.prompts = [new_prompt] if not exclusive else [*self.prompts, new_prompt]
        try:
            yield
        finally:
            self.prompts = original_prompts

    async def format_system_prompt(self, agent: Agent[Any, Any]) -> str:
        """Format complete system prompt."""
        if not self.dynamic and not self._cached:
            await self.refresh_cache()

        template = self._env.from_string(self.template or DEFAULT_TEMPLATE)
        result = await template.render_async(
            agent=agent,
            prompts=self.prompts,
            dynamic=self.dynamic,
            inject_agent_info=self.inject_agent_info,
            inject_tools=self.inject_tools,
            tool_usage_style=self.tool_usage_style,
        )
        return result.strip()

    __init__ 

    __init__(
    prompts: AnyPromptType | list[AnyPromptType] | None = None,
    template: str | None = None,
    dynamic: bool = True,
    context: AgentContext | None = None,
    inject_agent_info: bool = True,
    inject_tools: ToolInjectionMode = "off",
    tool_usage_style: ToolUsageStyle = "suggestive",
)

    Initialize prompt manager.

    Source code in src/llmling_agent/agent/sys_prompts.py 
    58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
    def __init__(
    self,
    prompts: AnyPromptType | list[AnyPromptType] | None = None,
    template: str | None = None,
    dynamic: bool = True,
    context: AgentContext | None = None,
    inject_agent_info: bool = True,
    inject_tools: ToolInjectionMode = "off",
    tool_usage_style: ToolUsageStyle = "suggestive",
):
    """Initialize prompt manager."""
    from jinjarope import Environment
    from toprompt import to_prompt

    match prompts:
        case list():
            self.prompts = prompts
        case None:
            self.prompts = []
        case _:
            self.prompts = [prompts]
    self.context = context
    self.template = template
    self.dynamic = dynamic
    self.inject_agent_info = inject_agent_info
    self.inject_tools = inject_tools
    self.tool_usage_style = tool_usage_style
    self._cached = False
    self._env = Environment(enable_async=True)
    self._env.filters["to_prompt"] = to_prompt

    add async 

    add(
    identifier: str,
    *,
    provider: str | None = None,
    version: str | None = None,
    variables: dict[str, Any] | None = None
)

    Add a system prompt using explicit parameters.

    Parameters:

    Name Type Description Default
    identifier str

    Prompt identifier/name

    		 required
    provider str | None

    Provider name (None = builtin)

    		 None
    version str | None

    Optional version string

    		 None
    variables dict[str, Any] | None

    Optional template variables

    		 None

    Examples:

    await sys_prompts.add("code_review", variables={"language": "python"}) await sys_prompts.add("expert", provider="langfuse", version="v2")

    Source code in src/llmling_agent/agent/sys_prompts.py 
    123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
    async def add(
    self,
    identifier: str,
    *,
    provider: str | None = None,
    version: str | None = None,
    variables: dict[str, Any] | None = None,
):
    """Add a system prompt using explicit parameters.

    Args:
        identifier: Prompt identifier/name
        provider: Provider name (None = builtin)
        version: Optional version string
        variables: Optional template variables

    Examples:
        await sys_prompts.add("code_review", variables={"language": "python"})
        await sys_prompts.add("expert", provider="langfuse", version="v2")
    """
    if not self.context:
        msg = "No context available to resolve prompts"
        raise RuntimeError(msg)

    try:
        content = await self.context.prompt_manager.get_from(
            identifier,
            provider=provider,
            version=version,
            variables=variables,
        )
        self.prompts.append(content)
    except Exception as e:
        ref = f"{provider + ':' if provider else ''}{identifier}"
        msg = f"Failed to add prompt {ref!r}"
        raise RuntimeError(msg) from e

    add_by_reference async 

    add_by_reference(reference: str)

    Add a system prompt using reference syntax.

    Parameters:

    Name Type Description Default
    reference str

    [provider:]identifier[@version][?var1=val1,...]

    		 required

    Examples:

    await sys_prompts.add_by_reference("code_review?language=python") await sys_prompts.add_by_reference("langfuse:expert@v2")

    Source code in src/llmling_agent/agent/sys_prompts.py 
    102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
    async def add_by_reference(self, reference: str):
    """Add a system prompt using reference syntax.

    Args:
        reference: [provider:]identifier[@version][?var1=val1,...]

    Examples:
        await sys_prompts.add_by_reference("code_review?language=python")
        await sys_prompts.add_by_reference("langfuse:expert@v2")
    """
    if not self.context:
        msg = "No context available to resolve prompts"
        raise RuntimeError(msg)

    try:
        content = await self.context.prompt_manager.get(reference)
        self.prompts.append(content)
    except Exception as e:
        msg = f"Failed to add prompt {reference!r}"
        raise RuntimeError(msg) from e

    clear 

    clear()

    Clear all system prompts.

    Source code in src/llmling_agent/agent/sys_prompts.py 
    160
161
162
    def clear(self):
    """Clear all system prompts."""
    self.prompts = []

    format_system_prompt async 

    format_system_prompt(agent: Agent[Any, Any]) -> str

    Format complete system prompt.

    Source code in src/llmling_agent/agent/sys_prompts.py 
    196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
    async def format_system_prompt(self, agent: Agent[Any, Any]) -> str:
    """Format complete system prompt."""
    if not self.dynamic and not self._cached:
        await self.refresh_cache()

    template = self._env.from_string(self.template or DEFAULT_TEMPLATE)
    result = await template.render_async(
        agent=agent,
        prompts=self.prompts,
        dynamic=self.dynamic,
        inject_agent_info=self.inject_agent_info,
        inject_tools=self.inject_tools,
        tool_usage_style=self.tool_usage_style,
    )
    return result.strip()

    refresh_cache async 

    refresh_cache()

    Force re-evaluation of prompts.

    Source code in src/llmling_agent/agent/sys_prompts.py 
    164
165
166
167
168
169
170
171
172
173
    async def refresh_cache(self):
    """Force re-evaluation of prompts."""
    from toprompt import to_prompt

    evaluated = []
    for prompt in self.prompts:
        result = await to_prompt(prompt)
        evaluated.append(result)
    self.prompts = evaluated
    self._cached = True

    temporary_prompt async 

    temporary_prompt(prompt: AnyPromptType, exclusive: bool = False) -> AsyncIterator[None]

    Temporarily override system prompts.

    Parameters:

    Name Type Description Default
    prompt AnyPromptType

    Single prompt or sequence of prompts to use temporarily

    		 required
    exclusive bool

    Whether to only use given prompt. If False, prompt will be appended to the agents prompts temporarily.

    		 False
    Source code in src/llmling_agent/agent/sys_prompts.py 
    175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
    @asynccontextmanager
async def temporary_prompt(
    self, prompt: AnyPromptType, exclusive: bool = False
) -> AsyncIterator[None]:
    """Temporarily override system prompts.

    Args:
        prompt: Single prompt or sequence of prompts to use temporarily
        exclusive: Whether to only use given prompt. If False, prompt will be
                   appended to the agents prompts temporarily.
    """
    from toprompt import to_prompt

    original_prompts = self.prompts.copy()
    new_prompt = await to_prompt(prompt)
    self.prompts = [new_prompt] if not exclusive else [*self.prompts, new_prompt]
    try:
        yield
    finally:
        self.prompts = original_prompts