Add modular agent instructions to Corpus model (partial #518) #521
Conversation
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
Resolves core backend requirements for #518 Changes: 1. Added corpus_agent_instructions and document_agent_instructions fields to Corpus model - Allows per-corpus customization of agent behavior - Falls back to settings defaults if not set 2. Created Django migration (0022_add_agent_instructions) 3. Added Django settings for default instructions - DEFAULT_DOCUMENT_AGENT_INSTRUCTIONS - improved instructions that emphasize using tools - DEFAULT_CORPUS_AGENT_INSTRUCTIONS - smarter instructions that handle empty corpus descriptions 4. Updated agent factories to use custom/default instructions - CoreDocumentAgentFactory.get_default_system_prompt now checks corpus.document_agent_instructions - CoreCorpusAgentFactory.get_default_system_prompt now checks corpus.corpus_agent_instructions - Falls back to settings defaults if custom instructions not provided Impact: - Improves corpus agent responses when corpus has no description but has documents - Allows corpus owners to customize agent behavior per corpus - Maintains backward compatibility with existing corpuses Remaining work for #518: - GraphQL mutations/queries for editing instructions via frontend - Frontend UI for corpus owners to edit agent instructions - Integration tests
This commit completes #518 by adding full GraphQL and frontend support for editing agent instructions per corpus. Backend (GraphQL): 1. Updated UpdateCorpusMutation to accept corpusAgentInstructions and documentAgentInstructions 2. Updated CorpusSerializer to include new fields in serialization 3. CorpusType automatically exposes new model fields via DjangoObjectType Frontend: 1. Updated UPDATE_CORPUS GraphQL mutation with new fields 2. Updated UpdateCorpusInputs interface to include new optional fields 3. Created CorpusAgentSettings component: - Displays two text areas for editing corpus and document agent instructions - Shows helpful descriptions for each instruction type - Tracks changes and enables save/reset buttons - Properly handles permissions (only corpus owners/editors can update) - Uses monospace font for better readability of instructions 4. Integrated CorpusAgentSettings into CorpusSettings page as new section Complete Solution: - Backend: Model fields + Django settings defaults ✅ - Backend: Agent factories use custom/default instructions ✅ - Backend: GraphQL mutations and queries ✅ - Frontend: UI for editing instructions ✅ - Tests: TypeScript compilation passes ✅ - Tests: Pre-commit hooks pass ✅ Impact: Corpus owners can now customize how AI agents behave when analyzing their corpus and documents. The improved default instructions make agents smarter about handling corpuses with empty descriptions but available documents.
Updated DEFAULT_DOCUMENT_AGENT_INSTRUCTIONS to use the original detailed instructions verbatim with visual separators, comprehensive search strategy, and explicit tool selection guidance. This provides more comprehensive guidance to document agents with: - Visual separators (━━━) for better readability - Detailed 5-step search strategy - Explicit tool selection guide - Comprehensive response requirements - Critical emphasis on citation protocol
The get_default_system_prompt method signature was updated to accept both document and corpus parameters, but the test was still checking for only the document parameter. Updated the test assertion to match the new signature.
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
Adds four new test cases to achieve complete coverage of the agent instruction selection logic in CoreDocumentAgentFactory and CoreCorpusAgentFactory: 1. test_document_agent_uses_default_instructions_when_corpus_has_none - Tests fallback to DEFAULT_DOCUMENT_AGENT_INSTRUCTIONS when corpus has no custom document_agent_instructions 2. test_corpus_agent_uses_default_instructions_when_corpus_has_none - Tests fallback to DEFAULT_CORPUS_AGENT_INSTRUCTIONS when corpus has no custom corpus_agent_instructions 3. test_document_agent_uses_custom_instructions_when_corpus_has_them - Tests using custom document_agent_instructions from corpus when available 4. test_corpus_agent_uses_custom_instructions_when_corpus_has_them - Tests using custom corpus_agent_instructions from corpus when available These tests ensure both branches of the if/else blocks are covered. Resolves missing coverage identified in PR #521.
Use document_id instead of passing model instance to database_sync_to_async to avoid query failures when crossing async/sync thread boundaries.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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
Fully resolves #518 - Complete implementation of modular, customizable agent instructions with backend infrastructure, GraphQL API, and frontend UI.
Problem
When a corpus has no description BUT has documents with annotations/analyses, the corpus agent gives unhelpful responses like "The corpus description is currently empty." This wastes the agent's potential to actually examine and summarize the available documents.
Complete Solution
1. Backend Infrastructure ✅
New Corpus Model Fields:
corpus_agent_instructions- Custom system prompt for corpus-level agentsdocument_agent_instructions- Custom system prompt for document-level agentsDjango Settings for Defaults:
DEFAULT_DOCUMENT_AGENT_INSTRUCTIONS- Improved instructions emphasizing tool usage and source citationDEFAULT_CORPUS_AGENT_INSTRUCTIONS- Smarter instructions that explicitly handle empty corpus descriptions:list_documents()when corpus description is emptyAgent Factory Integration:
CoreDocumentAgentFactory.get_default_system_prompt()checkscorpus.document_agent_instructionsfirst, falls back to settingsCoreCorpusAgentFactory.get_default_system_prompt()checkscorpus.corpus_agent_instructionsfirst, falls back to settings2. GraphQL API ✅
Updated
UpdateCorpusMutation:corpusAgentInstructionsargument (optional String)documentAgentInstructionsargument (optional String)Updated
CorpusSerializer:Updated
CorpusType:3. Frontend UI ✅
New
CorpusAgentSettingsComponent:Updated GraphQL Mutations:
UPDATE_CORPUSmutation accepts new optional fieldsUpdateCorpusInputsTypeScript interface updatedChanges Made
Modified Files:
opencontractserver/corpuses/models.py- Added instruction fieldsopencontractserver/llms/agents/core_agents.py- Updated factories to use custom/default instructionsconfig/settings/base.py- Added default instruction settingsconfig/graphql/mutations.py- Added mutation argumentsconfig/graphql/serializers.py- Added fields to serializerfrontend/src/graphql/mutations.ts- Updated mutation and typesfrontend/src/components/corpuses/CorpusSettings.tsx- Integrated new componentNew Files:
opencontractserver/corpuses/migrations/0022_add_agent_instructions.py- Database migrationfrontend/src/components/corpuses/CorpusAgentSettings.tsx- UI componentTest Plan
Impact
✅ Immediate improvement: Corpus agents are now smarter about handling empty corpus descriptions
✅ Customization: Corpus owners can fully customize agent behavior per corpus
✅ Backward compatible: Existing corpuses automatically use improved defaults
✅ Professional UI: Easy-to-use interface for editing instructions
✅ Full stack: Complete implementation from database to UI