feat: Consolidate duplicate models into unified architecture

[dstengle-roocode]

Summary

This PR consolidates the fragmented model architecture in the Knowledge Base Processor, eliminating duplicate models and creating a unified, maintainable structure with full backward compatibility.

Problem

The codebase had evolved into three parallel model hierarchies:

• Content Models: BaseKnowledgeModel → Document, ContentElement, etc.
• RDF-Aware Models: KbBaseEntity → KbDocument, KbPerson, etc.
• Simple Models: BaseModel → ExtractedEntity

This fragmentation led to:

• 50%+ duplicate model definitions
• Inconsistent RDF support
• Circular dependencies
• Maintenance overhead

Solution

Unified Model Architecture

Created a single, tiered inheritance hierarchy:

KnowledgeBaseEntity (Universal Base)
├── DocumentEntity → UnifiedDocument
├── ContentEntity → PersonEntity, OrganizationEntity, etc.
└── MarkdownEntity → TodoEntity, LinkEntity

Key Consolidations

• Base Classes: BaseKnowledgeModel + KbBaseEntity → KnowledgeBaseEntity
• Entity Models: ExtractedEntity + Kb*Entity → ContentEntity hierarchy
• Todo Models: TodoItem + KbTodoItem → TodoEntity
• Link Models: WikiLink + KbWikiLink → LinkEntity
• Document Models: Document + KbDocument → UnifiedDocument with integrated metadata

Benefits

• ✅ 50% reduction in duplicate model definitions
• ✅ Unified RDF support across all models
• ✅ Eliminated circular dependencies
• ✅ Cleaner import structure
• ✅ Better maintainability with focused model files
• ✅ Full backward compatibility through direct aliases

Files Changed

New Model Files

• models/base.py - Universal base classes
• models/entity_types.py - Specific entity models (Person, Org, Location, Date)
• models/todo.py - Unified todo model
• models/link.py - Unified link models
• models/document.py - Unified document models
• models/__init__.py - Clean imports with backward compatibility aliases

Documentation

• docs/architecture/model-consolidation-guide.md - Comprehensive migration guide
• CONSOLIDATION_SUMMARY.md - Executive summary of changes

Testing

• ✅ All model unit tests passing (22/22 in tests/models/)
• ✅ Full backward compatibility maintained - existing imports continue to work
• ✅ No breaking changes for existing functionality

Migration Path

The consolidation maintains full backward compatibility:

# Old imports continue to work
from knowledgebase_processor.models import ExtractedEntity, KbPerson, Document

# New unified imports also available
from knowledgebase_processor.models import ContentEntity, PersonEntity, UnifiedDocument

Next Steps

1. Gradually migrate services to use new unified models
2. Update tests to use new model structure
3. Deprecate old model files after full migration

🤖 Generated with Claude Code