feat: add vector database foundation abstractions for multi-provider support

[Krashnicov]

Overview

This PR introduces foundational abstractions for vector database operations, enabling support for multiple vector database providers (Supabase pgvector, Qdrant) through a unified interface.

Migrated from: dynamous-community/Archon-V2-Alpha#54 following repository transition to coleam00/Archon.

Core Abstractions Added

🗃️ BaseVectorStore - Abstract Interface

• Unified interface: connect(), create_collection(), upsert_vectors(), search(), delete()
• Data models: VectorDocument, VectorSearchResult
• Built-in validation and health monitoring
• Provider-agnostic design enabling factory pattern

🔐 CredentialProvider - Security Abstraction

• Abstract credential management interface
• LocalCredentialProvider for environment variable-based credentials
• Foundation for production credential providers
• Security-focused design with sanitization

📊 ProviderHealthStatus - Health Monitoring

• Enum-based status tracking (HEALTHY, UNHEALTHY, DEGRADED, UNKNOWN)
• Detailed error reporting and response time tracking
• Support for metadata and configuration validation

🛠️ Supporting Infrastructure

• Custom exceptions in service_exceptions.py
• Security logging with operation correlation IDs
• Validation framework for embedding dimensions

Benefits

✅ Provider Agnostic - Easy to add new vector database backends
✅ Type Safe - Full type hints with Pydantic models
✅ Production Ready - Comprehensive error handling and health monitoring
✅ Security Focused - Credential abstraction and secure logging
✅ Testing Friendly - Abstract interfaces enable easy mocking

File Structure

src/server/
├── models/
│   └── health_status.py           # Health monitoring models (131 lines)
├── services/storage/
│   ├── base_vector_store.py       # Core vector interface (360 lines)
│   └── credential_provider.py     # Credential management (243 lines)
└── exceptions/
    └── service_exceptions.py      # Vector-specific exceptions (18 lines)

Testing

All files pass:

• ✅ Import validation - All abstractions import successfully
• ✅ Type checking - Full type safety with abstract methods
• ✅ Interface compliance - Proper ABC patterns implemented

Breaking Changes

❌ None - This adds new abstractions without modifying existing code.

Next Steps

This foundation enables implementation of:

1. 🏭 Factory pattern for provider selection
2. 🔌 Concrete provider implementations (Supabase, Qdrant)
3. 🔗 Service layer integration
4. 📈 Health monitoring dashboard

Migration Notes

• Original PR: dynamous-community/Archon-V2-Alpha#54
• Updated file structure from python/src/ to src/ for new repository
• All functionality preserved with improved organization
• Ready for continued development in new upstream repository

🤖 Generated with Claude Code

Co-Authored-By: Claude [email protected]

[Wirasm]

@Krashnicov this looks like a solid contribution, how would it integrate with Archon?

[Wirasm]

Thank you for the contribution @Krashnicov Feel free to reopne and open a discussion about how you would like to integrate this to Archon