semantic update

backend/src/services/llm_provider.py

@@ -15,43 +15,74 @@ from cryptography.fernet import Fernet
 import os
 
 # [DEF:EncryptionManager:Class]
+# @TIER: CRITICAL
 # @PURPOSE: Handles encryption and decryption of sensitive data like API keys.
+# @INVARIANT: Uses a secret key from environment or a default one (fallback only for dev).
 class EncryptionManager:
-    # @INVARIANT: Uses a secret key from environment or a default one (fallback only for dev).
+    # [DEF:EncryptionManager.__init__:Function]
+    # @PURPOSE: Initialize the encryption manager with a Fernet key.
+    # @PRE: ENCRYPTION_KEY env var must be set or use default dev key.
+    # @POST: Fernet instance ready for encryption/decryption.
     def __init__(self):
         self.key = os.getenv("ENCRYPTION_KEY", "ZcytYzi0iHIl4Ttr-GdAEk117aGRogkGvN3wiTxrPpE=").encode()
         self.fernet = Fernet(self.key)
+    # [/DEF:EncryptionManager.__init__:Function]
 
+    # [DEF:EncryptionManager.encrypt:Function]
+    # @PURPOSE: Encrypt a plaintext string.
+    # @PRE: data must be a non-empty string.
+    # @POST: Returns encrypted string.
     def encrypt(self, data: str) -> str:
         return self.fernet.encrypt(data.encode()).decode()
+    # [/DEF:EncryptionManager.encrypt:Function]
 
+    # [DEF:EncryptionManager.decrypt:Function]
+    # @PURPOSE: Decrypt an encrypted string.
+    # @PRE: encrypted_data must be a valid Fernet-encrypted string.
+    # @POST: Returns original plaintext string.
     def decrypt(self, encrypted_data: str) -> str:
         return self.fernet.decrypt(encrypted_data.encode()).decode()
+    # [/DEF:EncryptionManager.decrypt:Function]
 # [/DEF:EncryptionManager:Class]
 
 # [DEF:LLMProviderService:Class]
+# @TIER: STANDARD
 # @PURPOSE: Service to manage LLM provider lifecycle.
 class LLMProviderService:
+    # [DEF:LLMProviderService.__init__:Function]
+    # @PURPOSE: Initialize the service with database session.
+    # @PRE: db must be a valid SQLAlchemy Session.
+    # @POST: Service ready for provider operations.
     def __init__(self, db: Session):
         self.db = db
         self.encryption = EncryptionManager()
+    # [/DEF:LLMProviderService.__init__:Function]
 
     # [DEF:get_all_providers:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Returns all configured LLM providers.
+    # @PRE: Database connection must be active.
+    # @POST: Returns list of all LLMProvider records.
     def get_all_providers(self) -> List[LLMProvider]:
         with belief_scope("get_all_providers"):
             return self.db.query(LLMProvider).all()
     # [/DEF:get_all_providers:Function]
 
     # [DEF:get_provider:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Returns a single LLM provider by ID.
+    # @PRE: provider_id must be a valid string.
+    # @POST: Returns LLMProvider or None if not found.
     def get_provider(self, provider_id: str) -> Optional[LLMProvider]:
         with belief_scope("get_provider"):
             return self.db.query(LLMProvider).filter(LLMProvider.id == provider_id).first()
     # [/DEF:get_provider:Function]
 
     # [DEF:create_provider:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Creates a new LLM provider with encrypted API key.
+    # @PRE: config must contain valid provider configuration.
+    # @POST: New provider created and persisted to database.
     def create_provider(self, config: LLMProviderConfig) -> LLMProvider:
         with belief_scope("create_provider"):
             encrypted_key = self.encryption.encrypt(config.api_key)
@@ -70,7 +101,10 @@ class LLMProviderService:
     # [/DEF:create_provider:Function]
 
     # [DEF:update_provider:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Updates an existing LLM provider.
+    # @PRE: provider_id must exist, config must be valid.
+    # @POST: Provider updated and persisted to database.
     def update_provider(self, provider_id: str, config: LLMProviderConfig) -> Optional[LLMProvider]:
         with belief_scope("update_provider"):
             db_provider = self.get_provider(provider_id)
@@ -92,7 +126,10 @@ class LLMProviderService:
     # [/DEF:update_provider:Function]
 
     # [DEF:delete_provider:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Deletes an LLM provider.
+    # @PRE: provider_id must exist.
+    # @POST: Provider removed from database.
     def delete_provider(self, provider_id: str) -> bool:
         with belief_scope("delete_provider"):
             db_provider = self.get_provider(provider_id)
@@ -104,7 +141,10 @@ class LLMProviderService:
     # [/DEF:delete_provider:Function]
 
     # [DEF:get_decrypted_api_key:Function]
+    # @TIER: STANDARD
     # @PURPOSE: Returns the decrypted API key for a provider.
+    # @PRE: provider_id must exist with valid encrypted key.
+    # @POST: Returns decrypted API key or None on failure.
     def get_decrypted_api_key(self, provider_id: str) -> Optional[str]:
         with belief_scope("get_decrypted_api_key"):
             db_provider = self.get_provider(provider_id)