Feature/prompt templates and versioning#155
Merged
Sanjusha-tridz merged 11 commits intoFeb 25, 2026
Merged
Conversation
Introduce Agent Prompt Category as a standalone DocType for organizing and grouping prompt templates. Supports hierarchical categories via parent_category self-link, with icon and color fields for UI display. This is the first step toward treating prompts as first-class reusable artifacts in HUF, preparing for prompt marketplace and library UX.
Introduce Agent Prompt as a first-class reusable artifact in HUF. Implements the immutable version model (Git-like) where each update creates a new row linked via previous_version. Key design decisions: - prompt_group: shared identifier across all versions of a lineage - forked_from: tracks lineage when prompts are forked/copied - is_latest: marks the current head version in each lineage - visibility: Public/App/Private for future marketplace support - is_system: protects HUF-managed prompts from user edits - slug: URL-friendly identifier, auto-generated from title - autoname: hash - supports immutable versioning without name conflicts This model supports version pinning, prompt marketplace, cross-app reuse, diffing, and audit trails.
Add prompt template support to Agent with backward-compatible defaults: - prompt_mode: Select (Local/Template), defaults to "Local" - agent_prompt: Link to Agent Prompt (visible in Template mode) - prompt_version_locked: lock agent to a specific template version - template_version_at_attach: records version at time of attachment - copied_from_prompt: hidden traceability link for detach operations Existing behavior is preserved: all current agents default to "Local" mode and continue using the instructions field directly. The instructions field gains depends_on for Local mode but remains functional for all backend reads. Validation updated to support both modes: Template mode requires agent_prompt link, Local mode requires instructions text.
Add prompt_resolver.py as the single source of truth for resolving an agent's effective prompt. All backend paths (sync runs, streaming, triggers, orchestration) now go through resolve_prompt() instead of reading agent_doc.instructions directly. Resolution rules: - Local mode: returns agent_doc.instructions (backward compatible) - Template mode (unlocked): loads prompt_body from linked Agent Prompt - Template mode (locked): walks the version lineage via prompt_group to find the exact version matching template_version_at_attach Also updates AgentManager.create_agent() and Agent.generate_default_plan() to use resolve_prompt() for consistent behavior.
Add prompt_api.py with server-side operations for the prompt template lifecycle: - create_new_version: immutable versioning — marks old as not-latest, creates new row, auto-updates unlocked agents - fork_prompt: creates independent copy with forked_from lineage - detach_from_template: copies resolved prompt to local, records copied_from_prompt for traceability - save_as_template: creates Agent Prompt from agent's local instructions - attach_template: switches agent to Template mode with optional version locking - get_version_history: returns full version lineage via prompt_group All methods are @frappe.whitelist() and follow Frappe patterns for permissions and error handling.
Update remaining places that read agent_doc.instructions directly to use resolve_prompt() instead: - agent_scheduler.py: scheduled agent runs now resolve templates - orchestrator.py: plan recreation uses resolved prompt - agent.py on_update: detect prompt changes from template switches - agent.py after_insert: pass resolved prompt to orchestration This ensures agents in Template mode work correctly across all execution paths: sync runs, streaming, scheduled triggers, and orchestration planning.
- Add 'agent_prompt.js' with client script for the Agent Prompt DocType
- Expose 'Create New Version' action for saved, non-system, latest prompts
- Expose 'Fork Prompt' action allowing independent lineages
- Wire UI buttons to backend whitelisted API ('huf.ai.prompt_api')
- Add confirmation dialogs and success routing to newly generated records
- Use 'resolve_prompt(agent_doc)' in agent_hooks.py instead of accessing 'agent_doc.instructions' directly. - Ensures DocEvent triggers now correctly resolve and pass Template mode instructions to the background worker, bringing it in line with 'agent_scheduler.py' and 'run_agent_sync'.
- Add 'prompt_template' link field to 'Agent Run' DocType to track which prompt template was used during the execution. - Update 'run_agent_sync' in 'agent_integration.py' to populate the 'prompt_template' field only when the agent's 'prompt_mode' is set to 'Template'.
esafwan
pushed a commit
that referenced
this pull request
Mar 10, 2026
…ersioning Feature/prompt templates and versioning
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a comprehensive prompt template management system for agents, enabling reusable prompt templates with versioning, forking, and flexible prompt mode switching between local and template-based approaches.
Key Changes
New DocTypes
Agent Prompt: Immutable versioned prompt templates with support for:
previous_versionandprompt_groupfieldsAgent Prompt Category: Hierarchical categorization for prompt templates with icon and color support
Agent Enhancements
prompt_modefield to switch between "Local" (inline instructions) and "Template" (linked prompt) modesagent_prompt,prompt_version_locked,template_version_at_attach,copied_from_promptNew API Module (
huf/ai/prompt_api.py)Whitelisted server-side operations for prompt management:
create_new_version(): Create immutable versions with automatic agent link updates for unlocked agentsfork_prompt(): Create independent prompt lineagesdetach_from_template(): Convert template-mode agents to local mode with traceabilitysave_as_template(): Save agent instructions as reusable templatesattach_template(): Link agents to templates with optional version lockingget_version_history(): Retrieve full version lineagePrompt Resolution (
huf/ai/prompt_resolver.py)Centralized
resolve_prompt()function that:Integration Updates
agent_integration.py,agent_scheduler.py, andorchestrator.pyto use centralized prompt resolution instead of directinstructionsfield accessImplementation Details
prompt_groupfield ties all versions of a prompt together for efficient history queriesinstructionsfield