Prompt Management & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
Prompt Management and Configuration in swe-term encompasses the structured definition of AI persona instructions, task-specific prompts for code analysis (such as ast-grep rule generation), and the orchestration of Large Language Model (LLM) pipelines for content distillation. The system utilizes centralized YAML configurations for high-level agent instructions and environment-driven variables for fine-tuning extraction behavior and model selection.
The configuration architecture is designed for extensibility, supporting multiple LLM providers (e.g., Ollama, Jina) and fallback mechanisms to ensure robustness during automated software engineering tasks. This includes strict safety and quality gates to validate LLM outputs against heuristic baselines.
LLM Pipeline Orchestration
The system orchestrates LLM calls primarily for content extraction and code search tasks. In the swe_distiller extension, the pipeline follows a prioritized order of providers, attempting to convert raw HTML into clean Markdown while applying safety checks to prevent hallucinations or low-quality rewrites.
Extraction Flow
The extraction logic utilizes a multi-provider strategy where successful results are validated against structural noise scores and safety metrics before being accepted.
The diagram shows the sequential attempt of LLM providers followed by validation gates. Sources: extensions/swe_distiller/src/extraction/llm.rs:24-60, extensions/swe_distiller/src/lib.rs:46-75
Provider Configuration
Providers and their operational constraints are managed via environment variables.
| Variable | Description | Default Value |
|---|---|---|
SWE_DISTILLER_LLM_PROVIDERS | Comma-separated list of prioritized models/APIs | gemma4:31b-cloud,reader-lm:1.5b,jina |
SWE_DISTILLER_LLM_TIMEOUT_MS | Network timeout for LLM requests | 60000 |
SWE_DISTILLER_LLM_MAX_INPUT_CHARS | Maximum characters sent to the model | 60000 |
OLLAMA_BASE_URL | Endpoint for local Ollama instance | http://127.0.0.1:11434 |
Sources: extensions/swe_distiller/src/extraction/llm.rs:11-13, extensions/swe_distiller/README.md:37-43
Structured Prompt Definitions
The system uses src/prompts.yaml to store complex, multi-step instructions for specific tools. A primary example is the ast-grep prompt, which guides the agent through natural language translation, rule development, and verification.
ast-grep Rule Development Prompt
The prompt for ast-grep defines a rigorous process for structural code search:
- Understand & Clarify: Resolve natural language ambiguities.
- Example Creation: Write a target code snippet.
- Rule Specification: Draft YAML rules using
pattern,kind, orrelationalselectors. - Verification: Use
test_match_code_ruleto ensure the rule matches the example. - Search: Execute the validated rule against the codebase.
Sources: src/prompts.yaml:1-25
Atomic and Relational Rules
The configuration documentation within the prompts specifies how the agent should use different rule categories:
Sources: src/prompts.yaml:80-116
Agent Persona and Principles
The core agent behavior is governed by AGENTS.md, which defines the "Polyglot Principal Engineer" persona. This configuration establishes a decision hierarchy that the agent must follow when interpreting prompts and executing tasks.
Decision Hierarchy
When principles conflict, the agent resolves decisions in the following order:
- Correctness & User Intent: Prioritize what was asked.
- Safety & Blast Radius: Protect data and production systems.
- Observability: Ensure failures are visible and diagnosis is cheap.
- Simplicity: Favor operational simplicity (e.g., 3am debuggability).
- Maintainability: Ensure code is readable and explainable.
Sources: AGENTS.md:20-39
Systems Preflight Checklist
Before acting on a prompt, the agent must perform an internal "preflight":
- Deconstruct: Break requests into system components.
- Tradeoff Analysis: Compare approaches.
- Blast Radius: Evaluate worst-case outcomes.
- Constraint Check: Verify permissions, cost, and time.
Sources: AGENTS.md:46-60
Output and Safety Constraints
Configuration also includes strict "Anti-Hallucination" rules and "Output Contracts" to maintain technical accuracy.
Safety Gates for LLM Output
In the context of content distillation, outputs are validated through specific checks:
- Word Count Overlap: Candidate must be between 75% and 135% of the original word count.
- Link Preservation: If the original had ≥6 links, the candidate must retain at least 55%.
- Heading Overlap: The first heading tokens must have at least 50% overlap.
- Noise Score: Penalizes navigation chrome like "Sign up" or "Search" strings.
Sources: extensions/swe_distiller/src/extraction/checks.rs:39-65, extensions/swe_distiller/src/extraction/llm.rs:50-58
Persona Guidelines
The agent is explicitly instructed never to invent command flags, API endpoints, or file paths. If uncertain, the agent must verify via official documentation or source code.
Sources: AGENTS.md:129-138
Conclusion
Prompt Management in swe-term is a multi-layered system that combines high-level architectural principles (as seen in AGENTS.md) with technical, tool-specific instructions (in prompts.yaml) and runtime LLM orchestration (in swe_distiller). This structure ensures that AI agents operate within defined safety boundaries while maintaining the flexibility to handle complex software engineering tasks like structural code search and content distillation.