{"record":{"id":"405dc05e8758bbe9","repo":"agentscope-ai/agentscope","slug":"hint-template-must-contain-exactly-one-context","errorCode":null,"errorMessage":"hint_template must contain exactly one '{context}' placeholder; found {count}.","messagePattern":"hint_template must contain exactly one '(.+?)' placeholder; found (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/agentscope/middleware/_rag.py","lineNumber":564,"sourceCode":"            ),\n        )\n\n        # ``hint_template`` is intentionally hidden from the JSON Schema\n        # exposed to the dock UI: the wrapper text is part of the\n        # middleware's prompt contract and exposing it through the dock\n        # invites session-by-session prompt drift.  It is still accepted\n        # for programmatic use.\n\n        @field_validator(\"hint_template\")\n        @classmethod\n        def _validate_hint_template(cls, value: str) -> str:\n            \"\"\"Reject templates with anything other than exactly one\n            ``{context}`` placeholder — :func:`_wrap_hint` substitutes on\n            the first occurrence, so zero placeholders silently drop the\n            matched content and multiple placeholders duplicate it.\"\"\"\n            count = value.count(\"{context}\")\n            if count != 1:\n                raise ValueError(\n                    \"hint_template must contain exactly one '{context}' \"\n                    f\"placeholder; found {count}.\",\n                )\n            return value\n\n    def __init__(\n        self,\n        knowledge_bases: list[\"KnowledgeBase\"],\n        parameters: \"RAGMiddleware.Parameters | None\" = None,\n    ) -> None:\n        \"\"\"Initialize the RAG middleware.\n\n        Args:\n            knowledge_bases (`list[KnowledgeBase]`):\n                The knowledge bases this agent searches.\n            parameters (`RAGMiddleware.Parameters | None`, optional):\n                Search-time knobs (mode, top_k, score threshold, hint\n                behaviour).  ``None`` uses the defaults of","sourceCodeStart":546,"sourceCodeEnd":582,"githubUrl":"https://github.com/agentscope-ai/agentscope/blob/e90f1c7592896cc95f6e5ee506194f533378247d/src/agentscope/middleware/_rag.py#L546-L582","documentation":"RAG middleware substitutes retrieved content into hint_template at its single '{context}' placeholder; a pydantic validator enforces exactly one occurrence because zero drops the content and multiple duplicates it.","triggerScenarios":"KnowledgeRetrieval(hint_template='Answer using:') (no placeholder), or '...{context}...{context}...' (two); literal braces like '{{context}}' also count as zero.","commonSituations":"Customizing the retrieval prompt and forgetting or doubling the placeholder; escaping braces incorrectly; template edited from f-string habits.","solutions":["Include exactly one '{context}' in hint_template","Escape literal braces as '{{' and '}}' while keeping one '{context}'","Omit hint_template entirely to use the built-in default"],"exampleFix":"# before\nKnowledgeRetrieval(hint_template='Context:\\n{{context}}')\n# after\nKnowledgeRetrieval(hint_template='Context:\\n{context}')","handlingStrategy":"validation","validationCode":"count = hint_template.count('{context}')\nassert count == 1, f'hint_template needs exactly one {{context}}; found {count}'","typeGuard":null,"tryCatchPattern":"try:\n    kr = KnowledgeRetrieval(hint_template=t)\nexcept ValueError:\n    t = t if t.count('{context}') == 1 else DEFAULT_HINT\n    kr = KnowledgeRetrieval(hint_template=t)","preventionTips":["Add a unit test asserting your template contains exactly one '{context}'","Omit hint_template to use the default rather than hand-editing"],"tags":["rag","template","validation","placeholder"],"backgroundTag":"template-placeholder-validation","analyzedSha":"e90f1c7592896cc95f6e5ee506194f533378247d","analyzedAt":"2026-08-28T18:24:12.087Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}