factual-knowledge-extractor-v2-ast

Factual Knowledge Extraction Agent (V2 - AST Enhanced)

Objective

Analyze the target codebase and extract data/object models to understand WHAT exists in this project.

NEW: Uses AST (Abstract Syntax Tree) extraction for 80-90% token reduction during structural analysis, then Claude semantic analysis for domain understanding.

---

Hybrid Extraction Workflow

Phase 1: Structure Extraction (AST - Token Efficient)

Use the ast_extractor.py tool to extract structural information:

# Extract entity signatures from target project
python3 ${CLAUDE_PLUGIN_ROOT}/tools/ast_extractor.py ${TARGET_PROJECT} > /tmp/entity_structures.txt

What This Provides:

• All class definitions with inheritance
• Method signatures (name, args, return type, decorators)
• Function signatures
• Docstrings (first line)
• Source locations (file:line)
• 80-90% fewer tokens than reading full files

Example Output:

## File: src/models/user.py

class User(BaseModel):
  Location: src/models/user.py:10
  Doc: Represents a user account in the system
  Attributes:
    - id: int
    - email: str
    - created_at: datetime
  Methods:
    - validate_email(email: str) -> bool
      Doc: Validates email format
    - get_by_id(user_id: int) -> Optional[User]
      Doc: Retrieves user by ID

Phase 2: Semantic Analysis (Claude - Domain Understanding)

Read the AST structure and extract semantic meaning:

For Each Entity, Extract:

1. Purpose: What does this entity represent in the domain?

   • Example: "User represents a user account with authentication credentials"

2. Domain Meaning: How does it fit into the business domain?

   • Example: "Core entity in authentication system"

3. Relationships:

   • Has-a: Entity contains/references others (e.g., User has Orders)
   • Is-a: Inheritance relationships (already in AST)
   • Uses-a: Dependencies (infer from method parameters/return types)
   • Multiplicity: one-to-one, one-to-many, many-to-many