feat(graph): require evidence on manual concept creation, add evidence endpoint

aaronsb · aaronsb · commit 62f587dcc48f · 2026-03-26T18:20:16.000-05:00
Manually created concepts were born with zero evidence instances, making them ungrounded. Now evidence_text is required when creating concepts via API/CLI/MCP (except match_only mode and LLM extraction). Evidence is stored as an Instance node linked to the concept's synthetic source. Also adds: - POST /concepts/{id}/evidence endpoint for adding evidence to existing concepts - add_evidence action on the MCP concept tool - evidence_text parameter on the MCP graph tool (create concept + queue) - Missing @types dev deps that were causing pre-existing TS build failures
diff --git a/api/app/models/concepts.py b/api/app/models/concepts.py
@@ -74,6 +74,12 @@ class ConceptCreate(BaseModel):
         CreationMethod.API,
         description="How this concept is being created"
     )
+    evidence_text: Optional[str] = Field(
+        None,
+        description="Evidence/rationale for the concept (required for manual creation via API/CLI/MCP)",
+        min_length=10,
+        max_length=2000
+    )
 
     class Config:
         json_schema_extra = {
@@ -88,6 +94,17 @@ class Config:
         }
 
 
+class EvidenceCreate(BaseModel):
+    """Request to add evidence to an existing concept."""
+
+    evidence_text: str = Field(
+        ...,
+        description="Evidence/rationale text supporting the concept",
+        min_length=10,
+        max_length=2000
+    )
+
+
 class ConceptUpdate(BaseModel):
     """Request to update an existing concept (partial update)."""
 
diff --git a/api/app/routes/concepts.py b/api/app/routes/concepts.py
@@ -18,6 +18,7 @@
     ConceptResponse,
     ConceptListResponse,
     CreationMethod,
+    EvidenceCreate,
 )
 from ..models.auth import UserInDB
 from ..dependencies.auth import require_permission
@@ -277,3 +278,65 @@ async def delete_concept(
             status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
             detail="Failed to delete concept"
         )
+
+
+@router.post(
+    "/{concept_id}/evidence",
+    status_code=status.HTTP_201_CREATED,
+    summary="Add evidence to a concept"
+)
+async def add_evidence(
+    concept_id: str,
+    request: EvidenceCreate,
+    current_user: UserInDB = Depends(require_permission("graph", "write"))
+):
+    """
+    Add evidence text to an existing concept.
+
+    Creates an Instance node with the evidence text and links it
+    to the concept via a synthetic source.
+
+    Requires `graph:write` permission.
+    """
+    age_client = get_age_client()
+    service = get_concept_service(age_client)
+
+    try:
+        result = await service.add_evidence(
+            concept_id=concept_id,
+            evidence_text=request.evidence_text,
+            user_id=str(current_user.id) if current_user else None
+        )
+
+        log_audit_standalone(
+            age_client=age_client,
+            user_id=current_user.id if current_user else None,
+            action=AuditAction.CREATE_CONCEPT.value,
+            resource_type="evidence",
+            resource_id=result["instance_id"],
+            details={
+                "concept_id": concept_id,
+                "evidence_text": request.evidence_text[:100]
+            },
+            outcome="success"
+        )
+
+        age_client.refresh_epoch()
+
+        return result
+    except ValueError as e:
+        if "not found" in str(e).lower():
+            raise HTTPException(
+                status_code=status.HTTP_404_NOT_FOUND,
+                detail=str(e)
+            )
+        raise HTTPException(
+            status_code=status.HTTP_400_BAD_REQUEST,
+            detail=str(e)
+        )
+    except Exception as e:
+        logger.error(f"Failed to add evidence to concept {concept_id}: {e}")
+        raise HTTPException(
+            status_code=status.HTTP_500_INTERNAL_SERVER_ERROR,
+            detail="Failed to add evidence"
+        )
diff --git a/api/app/services/concept_service.py b/api/app/services/concept_service.py
@@ -113,6 +113,13 @@ async def create_concept(
                 f"No matching concept found for '{request.label}' in ontology '{request.ontology}'"
             )
 
+        # Require evidence for manual concept creation
+        if request.creation_method != CreationMethod.LLM_EXTRACTION and not request.evidence_text:
+            raise ValueError(
+                "evidence_text is required when creating a concept manually. "
+                "Provide the rationale or supporting evidence (min 10 characters)."
+            )
+
         # Create new concept
         concept_id = f"c_{uuid4().hex[:12]}"
 
@@ -138,6 +145,14 @@ async def create_concept(
         # Link concept to source
         self.age_client.link_concept_to_source(concept_id, source_id)
 
+        # Create evidence instance if evidence_text provided
+        if request.evidence_text:
+            await self._create_evidence_instance(
+                concept_id=concept_id,
+                source_id=source_id,
+                evidence_text=request.evidence_text
+            )
+
         # Store creation metadata (in concept properties)
         await self._set_concept_metadata(
             concept_id=concept_id,
@@ -215,6 +230,75 @@ async def _create_synthetic_source(
 
         return source_id
 
+    async def _create_evidence_instance(
+        self,
+        concept_id: str,
+        source_id: str,
+        evidence_text: str
+    ) -> str:
+        """Create an Instance node and link it to a concept and source."""
+        instance_id = f"i_{uuid4().hex[:12]}"
+        self.age_client.create_instance_node(
+            instance_id=instance_id,
+            quote=evidence_text
+        )
+        self.age_client.link_instance_to_concept_and_source(
+            instance_id=instance_id,
+            concept_id=concept_id,
+            source_id=source_id
+        )
+        return instance_id
+
+    async def add_evidence(
+        self,
+        concept_id: str,
+        evidence_text: str,
+        user_id: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """Add evidence to an existing concept.
+
+        Creates a synthetic source, an Instance node with the evidence text,
+        and links them: Concept -[EVIDENCED_BY]-> Instance -[FROM_SOURCE]-> Source.
+        """
+        # Verify concept exists
+        query = """
+        MATCH (c:Concept {concept_id: $concept_id})
+        RETURN c.label as label, c.ontology as ontology
+        """
+        result = self.age_client._execute_cypher(
+            query, params={"concept_id": concept_id}, fetch_one=True
+        )
+        if not result:
+            raise ValueError(f"Concept {concept_id} not found")
+
+        label = result.get("label", "unknown")
+        ontology = result.get("ontology", "unknown")
+
+        # Create synthetic source for this evidence
+        source_id = await self._create_synthetic_source(
+            ontology=ontology,
+            concept_label=label,
+            creation_method=CreationMethod.API,
+            user_id=user_id
+        )
+
+        # Link concept to the new source
+        self.age_client.link_concept_to_source(concept_id, source_id)
+
+        # Create instance and link
+        instance_id = await self._create_evidence_instance(
+            concept_id=concept_id,
+            source_id=source_id,
+            evidence_text=evidence_text
+        )
+
+        return {
+            "concept_id": concept_id,
+            "instance_id": instance_id,
+            "source_id": source_id,
+            "evidence_text": evidence_text
+        }
+
     async def _set_concept_metadata(
         self,
         concept_id: str,
diff --git a/cli/package.json b/cli/package.json
@@ -72,8 +72,12 @@
     "table": "^6.8.1"
   },
   "devDependencies": {
+    "@types/babel__generator": "^7.27.0",
+    "@types/babel__template": "^7.4.4",
+    "@types/istanbul-lib-report": "^3.0.3",
     "@types/jest": "^29.5.0",
     "@types/node": "^20.10.0",
+    "@types/yargs-parser": "^21.0.3",
     "jest": "^29.7.0",
     "ts-jest": "^29.1.0",
     "typescript": "^5.3.0"
diff --git a/cli/src/api/client.ts b/cli/src/api/client.ts
@@ -72,6 +72,7 @@ import {
   EdgeListResponse,
   BatchCreateRequest,
   BatchCreateResponse,
+  EvidenceResponse,
 } from '../types';
 
 export class KnowledgeGraphClient {
@@ -733,6 +734,17 @@ export class KnowledgeGraphClient {
     return response.data;
   }
 
+  /**
+   * Add evidence to an existing concept.
+   */
+  async addEvidence(conceptId: string, evidenceText: string): Promise<EvidenceResponse> {
+    const response = await this.client.post(
+      `/concepts/${encodeURIComponent(conceptId)}/evidence`,
+      { evidence_text: evidenceText }
+    );
+    return response.data;
+  }
+
   /**
    * Get a concept by ID.
    */
diff --git a/cli/src/mcp-server.ts b/cli/src/mcp-server.ts
@@ -442,13 +442,17 @@ For multi-step workflows (search → connect → expand → filter), compose the
           properties: {
             action: {
               type: 'string',
-              enum: ['details', 'related', 'connect'],
-              description: 'Operation: "details" (get ALL evidence), "related" (explore neighborhood), "connect" (find paths)',
+              enum: ['details', 'related', 'connect', 'add_evidence'],
+              description: 'Operation: "details" (get ALL evidence), "related" (explore neighborhood), "connect" (find paths), "add_evidence" (attach evidence text to a concept)',
             },
-            // For details and related
+            // For details, related, and add_evidence
             concept_id: {
               type: 'string',
-              description: 'Concept ID (required for details, related)',
+              description: 'Concept ID (required for details, related, add_evidence)',
+            },
+            evidence_text: {
+              type: 'string',
+              description: 'Evidence/rationale text to attach to a concept (required for add_evidence, min 10 chars)',
             },
             include_grounding: {
               type: 'boolean',
@@ -1064,6 +1068,7 @@ Queue executes sequentially, continues past errors by default (set continue_on_e
                   description: { type: 'string' },
                   search_terms: { type: 'array', items: { type: 'string' } },
                   matching_mode: { type: 'string', enum: ['auto', 'force_create', 'match_only'] },
+                  evidence_text: { type: 'string' },
                   concept_id: { type: 'string' },
                   from_concept_id: { type: 'string' },
                   to_concept_id: { type: 'string' },
@@ -1109,6 +1114,10 @@ Queue executes sequentially, continues past errors by default (set continue_on_e
               description: 'How to handle similar existing concepts (default: auto)',
               default: 'auto',
             },
+            evidence_text: {
+              type: 'string',
+              description: 'Evidence/rationale for the concept (required for create concept, min 10 chars). Stored as an Instance node.',
+            },
             // Edge fields
             from_concept_id: {
               type: 'string',
@@ -1706,6 +1715,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
           }
 
+          case 'add_evidence': {
+            const conceptId = toolArgs.concept_id as string;
+            const evidenceText = toolArgs.evidence_text as string;
+
+            if (!conceptId) {
+              throw new Error('concept_id is required for add_evidence');
+            }
+            if (!evidenceText || evidenceText.length < 10) {
+              throw new Error('evidence_text is required and must be at least 10 characters');
+            }
+
+            const result = await client.addEvidence(conceptId, evidenceText);
+
+            return {
+              content: [{ type: 'text', text: `Evidence added to concept ${result.concept_id}\n\nInstance: ${result.instance_id}\nSource: ${result.source_id}\nText: ${result.evidence_text}` }],
+            };
+          }
+
           default:
             throw new Error(`Unknown concept action: ${action}`);
         }
@@ -2614,12 +2641,19 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         switch (action) {
           case 'create': {
             if (entity === 'concept') {
+              const evidenceText = toolArgs.evidence_text as string | undefined;
+              const matchingMode = toolArgs.matching_mode as string | undefined;
+              // Require evidence_text unless match_only (linking to existing concept)
+              if (matchingMode !== 'match_only' && (!evidenceText || evidenceText.length < 10)) {
+                throw new Error('evidence_text is required when creating a concept (min 10 characters). Provide the rationale or supporting evidence for why this concept exists.');
+              }
               const result = await executor.createConcept({
                 label: toolArgs.label as string,
                 ontology: toolArgs.ontology as string,
                 description: toolArgs.description as string | undefined,
                 search_terms: toolArgs.search_terms as string[] | undefined,
-                matching_mode: toolArgs.matching_mode as 'auto' | 'force_create' | 'match_only' | undefined,
+                matching_mode: matchingMode as 'auto' | 'force_create' | 'match_only' | undefined,
+                evidence_text: evidenceText,
               });
               if (!result.success) throw new Error(result.error);
               return {
diff --git a/cli/src/mcp/graph-operations.ts b/cli/src/mcp/graph-operations.ts
@@ -96,6 +96,7 @@ export interface CreateConceptParams {
   description?: string;
   search_terms?: string[];
   matching_mode?: MatchingMode;
+  evidence_text?: string;
 }
 
 /**
@@ -191,6 +192,7 @@ export interface QueueOperation {
   description?: string;
   search_terms?: string[];
   matching_mode?: MatchingMode;
+  evidence_text?: string;
   concept_id?: string;
   cascade?: boolean;
   label_contains?: string;
@@ -354,6 +356,7 @@ export class GraphOperationExecutor {
         search_terms: params.search_terms,
         matching_mode: params.matching_mode || 'auto',
         creation_method: 'mcp',
+        evidence_text: params.evidence_text,
       });
 
       return { success: true, data: result };
@@ -660,6 +663,7 @@ export class GraphOperationExecutor {
         description: op.description,
         search_terms: op.search_terms,
         matching_mode: op.matching_mode,
+        evidence_text: op.evidence_text,
       });
       if (!result.success) {
         throw new Error(result.error);
diff --git a/cli/src/types/index.ts b/cli/src/types/index.ts
@@ -1048,6 +1048,24 @@ export interface ConceptCreate {
   search_terms?: string[];
   matching_mode?: MatchingMode;
   creation_method?: CreationMethod;
+  evidence_text?: string;
+}
+
+/**
+ * Request to add evidence to an existing concept.
+ */
+export interface EvidenceCreate {
+  evidence_text: string;
+}
+
+/**
+ * Response from adding evidence to a concept.
+ */
+export interface EvidenceResponse {
+  concept_id: string;
+  instance_id: string;
+  source_id: string;
+  evidence_text: string;
 }
 
 /**
diff --git a/docs/reference/mcp/README.md b/docs/reference/mcp/README.md
diff --git a/docs/reference/mcp/tools/concept.md b/docs/reference/mcp/tools/concept.md
diff --git a/docs/reference/mcp/tools/graph.md b/docs/reference/mcp/tools/graph.md
