hindsight-api 0.0.17__py3-none-any.whl → 0.0.20__py3-none-any.whl

hindsight_api/api/__init__.py

@@ -87,7 +87,7 @@ from .http import (
     ReflectRequest,
     ReflectResponse,
     CreateBankRequest,
-    PersonalityTraits,
+    DispositionTraits,
 )
 
 __all__ = [
@@ -100,5 +100,5 @@ __all__ = [
     "ReflectRequest",
     "ReflectResponse",
     "CreateBankRequest",
-    "PersonalityTraits",
+    "DispositionTraits",
 ]

hindsight_api/api/http.py

@@ -84,7 +84,7 @@ class RecallRequest(BaseModel):
     model_config = ConfigDict(json_schema_extra={
         "example": {
             "query": "What did Alice say about machine learning?",
-            "types": ["world", "bank"],
+            "types": ["world", "experience"],
             "budget": "mid",
             "max_tokens": 4096,
             "trace": True,
@@ -131,7 +131,7 @@ class RecallResult(BaseModel):
 
     id: str
     text: str
-    type: Optional[str] = None  # fact type: world, agent, opinion, observation
+    type: Optional[str] = None  # fact type: world, experience, opinion, observation
     entities: Optional[List[str]] = None  # Entity names mentioned in this fact
     context: Optional[str] = None
     occurred_start: Optional[str] = None  # ISO format date when the event started
@@ -397,7 +397,7 @@ class ReflectFact(BaseModel):
 
     id: Optional[str] = None
     text: str
-    type: Optional[str] = None  # fact type: world, agent, opinion
+    type: Optional[str] = None  # fact type: world, experience, opinion
     context: Optional[str] = None
     occurred_start: Optional[str] = None
     occurred_end: Optional[str] = None
@@ -417,7 +417,7 @@ class ReflectResponse(BaseModel):
                 {
                     "id": "456",
                     "text": "I discussed AI applications last week",
-                    "type": "bank"
+                    "type": "experience"
                 }
             ]
         }
@@ -438,8 +438,8 @@ class BanksResponse(BaseModel):
     banks: List[str]
 
 
-class PersonalityTraits(BaseModel):
-    """Personality traits based on Big Five model."""
+class DispositionTraits(BaseModel):
+    """Disposition traits based on Big Five model."""
     model_config = ConfigDict(json_schema_extra={
         "example": {
             "openness": 0.8,
@@ -456,7 +456,7 @@ class PersonalityTraits(BaseModel):
     extraversion: float = Field(ge=0.0, le=1.0, description="Extraversion (0-1)")
     agreeableness: float = Field(ge=0.0, le=1.0, description="Agreeableness (0-1)")
     neuroticism: float = Field(ge=0.0, le=1.0, description="Neuroticism (0-1)")
-    bias_strength: float = Field(ge=0.0, le=1.0, description="How strongly personality influences opinions (0-1)")
+    bias_strength: float = Field(ge=0.0, le=1.0, description="How strongly disposition influences opinions (0-1)")
 
 
 class BankProfileResponse(BaseModel):
@@ -465,7 +465,7 @@ class BankProfileResponse(BaseModel):
         "example": {
             "bank_id": "user123",
             "name": "Alice",
-            "personality": {
+            "disposition": {
                 "openness": 0.8,
                 "conscientiousness": 0.6,
                 "extraversion": 0.5,
@@ -479,13 +479,13 @@ class BankProfileResponse(BaseModel):
 
     bank_id: str
     name: str
-    personality: PersonalityTraits
+    disposition: DispositionTraits
     background: str
 
 
-class UpdatePersonalityRequest(BaseModel):
-    """Request model for updating personality traits."""
-    personality: PersonalityTraits
+class UpdateDispositionRequest(BaseModel):
+    """Request model for updating disposition traits."""
+    disposition: DispositionTraits
 
 
 class AddBackgroundRequest(BaseModel):
@@ -493,14 +493,14 @@ class AddBackgroundRequest(BaseModel):
     model_config = ConfigDict(json_schema_extra={
         "example": {
             "content": "I was born in Texas",
-            "update_personality": True
+            "update_disposition": True
         }
     })
 
     content: str = Field(description="New background information to add or merge")
-    update_personality: bool = Field(
+    update_disposition: bool = Field(
         default=True,
-        description="If true, infer Big Five personality traits from the merged background (default: true)"
+        description="If true, infer Big Five disposition traits from the merged background (default: true)"
     )
 
 
@@ -509,7 +509,7 @@ class BackgroundResponse(BaseModel):
     model_config = ConfigDict(json_schema_extra={
         "example": {
             "background": "I was born in Texas. I am a software engineer with 10 years of experience.",
-            "personality": {
+            "disposition": {
                 "openness": 0.7,
                 "conscientiousness": 0.6,
                 "extraversion": 0.5,
@@ -521,14 +521,14 @@ class BackgroundResponse(BaseModel):
     })
 
     background: str
-    personality: Optional[PersonalityTraits] = None
+    disposition: Optional[DispositionTraits] = None
 
 
 class BankListItem(BaseModel):
     """Bank list item with profile summary."""
     bank_id: str
     name: str
-    personality: PersonalityTraits
+    disposition: DispositionTraits
     background: str
     created_at: Optional[str] = None
     updated_at: Optional[str] = None
@@ -542,7 +542,7 @@ class BankListResponse(BaseModel):
                 {
                     "bank_id": "user123",
                     "name": "Alice",
-                    "personality": {
+                    "disposition": {
                         "openness": 0.5,
                         "conscientiousness": 0.5,
                         "extraversion": 0.5,
@@ -566,7 +566,7 @@ class CreateBankRequest(BaseModel):
     model_config = ConfigDict(json_schema_extra={
         "example": {
             "name": "Alice",
-            "personality": {
+            "disposition": {
                 "openness": 0.8,
                 "conscientiousness": 0.6,
                 "extraversion": 0.5,
@@ -579,7 +579,7 @@ class CreateBankRequest(BaseModel):
     })
 
     name: Optional[str] = None
-    personality: Optional[PersonalityTraits] = None
+    disposition: Optional[DispositionTraits] = None
     background: Optional[str] = None
 
 
@@ -833,7 +833,7 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/graph",
         response_model=GraphDataResponse,
         summary="Get memory graph data",
-        description="Retrieve graph data for visualization, optionally filtered by type (world/agent/opinion). Limited to 1000 most recent items.",
+        description="Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.",
         operation_id="get_graph"
     )
     async def api_graph(bank_id: str,
@@ -871,7 +871,7 @@ def _register_routes(app: FastAPI):
 
         Args:
             bank_id: Memory Bank ID (from path)
-            type: Filter by fact type (world, agent, opinion)
+            type: Filter by fact type (world, experience, opinion)
             q: Search query for full-text search (searches text and context)
             limit: Maximum number of results (default: 100)
             offset: Offset for pagination (default: 0)
@@ -901,7 +901,7 @@ def _register_routes(app: FastAPI):
 
     The type parameter is optional and must be one of:
     - 'world': General knowledge about people, places, events, and things that happen
-    - 'bank': Memories about what the AI agent did, actions taken, and tasks performed
+    - 'experience': Memories about experience, conversations, actions taken, and tasks performed
     - 'opinion': The bank's formed beliefs, perspectives, and viewpoints
 
     Set include_entities=true to get entity observations alongside recall results.
@@ -914,10 +914,10 @@ def _register_routes(app: FastAPI):
 
         try:
             # Validate types
-            valid_fact_types = ["world", "bank", "opinion"]
+            valid_fact_types = ["world", "experience", "opinion"]
 
-            # Default to world, agent, opinion if not specified (exclude observation by default)
-            fact_types = request.types if request.types else ["world", "bank", "opinion"]
+            # Default to world, experience, opinion if not specified (exclude observation by default)
+            fact_types = request.types if request.types else ["world", "experience", "opinion"]
             for ft in fact_types:
                 if ft not in valid_fact_types:
                     raise HTTPException(
@@ -1026,7 +1026,7 @@ def _register_routes(app: FastAPI):
     Reflect and formulate an answer using bank identity, world facts, and opinions.
 
     This endpoint:
-    1. Retrieves agent facts (bank's identity)
+    1. Retrieves experience (conversations and events)
     2. Retrieves world facts relevant to the query
     3. Retrieves existing opinions (bank's perspectives)
     4. Uses LLM to formulate a contextual answer
@@ -1579,19 +1579,19 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/profile",
         response_model=BankProfileResponse,
         summary="Get memory bank profile",
-        description="Get personality traits and background for a memory bank. Auto-creates agent with defaults if not exists.",
+        description="Get disposition traits and background for a memory bank. Auto-creates agent with defaults if not exists.",
         operation_id="get_bank_profile"
     )
     async def api_get_bank_profile(bank_id: str):
-        """Get memory bank profile (personality + background)."""
+        """Get memory bank profile (disposition + background)."""
         try:
             profile = await app.state.memory.get_bank_profile(bank_id)
-            # Convert PersonalityTraits object to dict for Pydantic
-            personality_dict = profile["personality"].model_dump() if hasattr(profile["personality"], 'model_dump') else dict(profile["personality"])
+            # Convert DispositionTraits object to dict for Pydantic
+            disposition_dict = profile["disposition"].model_dump() if hasattr(profile["disposition"], 'model_dump') else dict(profile["disposition"])
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=profile["name"],
-                personality=PersonalityTraits(**personality_dict),
+                disposition=DispositionTraits(**disposition_dict),
                 background=profile["background"]
             )
         except Exception as e:
@@ -1604,28 +1604,28 @@ This operation cannot be undone.
     @app.put(
         "/v1/default/banks/{bank_id}/profile",
         response_model=BankProfileResponse,
-        summary="Update memory bank personality",
-        description="Update bank's Big Five personality traits and bias strength",
-        operation_id="update_bank_personality"
+        summary="Update memory bank disposition",
+        description="Update bank's Big Five disposition traits and bias strength",
+        operation_id="update_bank_disposition"
     )
-    async def api_update_bank_personality(bank_id: str,
-        request: UpdatePersonalityRequest
+    async def api_update_bank_disposition(bank_id: str,
+        request: UpdateDispositionRequest
     ):
-        """Update bank personality traits."""
+        """Update bank disposition traits."""
         try:
-            # Update personality
-            await app.state.memory.update_bank_personality(
+            # Update disposition
+            await app.state.memory.update_bank_disposition(
                 bank_id,
-                request.personality.model_dump()
+                request.disposition.model_dump()
             )
 
             # Get updated profile
             profile = await app.state.memory.get_bank_profile(bank_id)
-            personality_dict = profile["personality"].model_dump() if hasattr(profile["personality"], 'model_dump') else dict(profile["personality"])
+            disposition_dict = profile["disposition"].model_dump() if hasattr(profile["disposition"], 'model_dump') else dict(profile["disposition"])
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=profile["name"],
-                personality=PersonalityTraits(**personality_dict),
+                disposition=DispositionTraits(**disposition_dict),
                 background=profile["background"]
             )
         except Exception as e:
@@ -1639,23 +1639,23 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/background",
         response_model=BackgroundResponse,
         summary="Add/merge memory bank background",
-        description="Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers personality traits.",
+        description="Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers disposition traits.",
         operation_id="add_bank_background"
     )
     async def api_add_bank_background(bank_id: str,
         request: AddBackgroundRequest
     ):
-        """Add or merge bank background information. Optionally infer personality traits."""
+        """Add or merge bank background information. Optionally infer disposition traits."""
         try:
             result = await app.state.memory.merge_bank_background(
                 bank_id,
                 request.content,
-                update_personality=request.update_personality
+                update_disposition=request.update_disposition
             )
 
             response = BackgroundResponse(background=result["background"])
-            if "personality" in result:
-                response.personality = PersonalityTraits(**result["personality"])
+            if "disposition" in result:
+                response.disposition = DispositionTraits(**result["disposition"])
 
             return response
         except Exception as e:
@@ -1669,13 +1669,13 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}",
         response_model=BankProfileResponse,
         summary="Create or update memory bank",
-        description="Create a new agent or update existing agent with personality and background. Auto-fills missing fields with defaults.",
+        description="Create a new agent or update existing agent with disposition and background. Auto-fills missing fields with defaults.",
         operation_id="create_or_update_bank"
     )
     async def api_create_or_update_bank(bank_id: str,
         request: CreateBankRequest
     ):
-        """Create or update an agent with personality and background."""
+        """Create or update an agent with disposition and background."""
         try:
             # Get existing profile or create with defaults
             profile = await app.state.memory.get_bank_profile(bank_id)
@@ -1696,13 +1696,13 @@ This operation cannot be undone.
                     )
                 profile["name"] = request.name
 
-            # Update personality if provided
-            if request.personality is not None:
-                await app.state.memory.update_bank_personality(
+            # Update disposition if provided
+            if request.disposition is not None:
+                await app.state.memory.update_bank_disposition(
                     bank_id,
-                    request.personality.model_dump()
+                    request.disposition.model_dump()
                 )
-                profile["personality"] = request.personality.model_dump()
+                profile["disposition"] = request.disposition.model_dump()
 
             # Update background if provided (replace, not merge)
             if request.background is not None:
@@ -1722,11 +1722,11 @@ This operation cannot be undone.
 
             # Get final profile
             final_profile = await app.state.memory.get_bank_profile(bank_id)
-            personality_dict = final_profile["personality"].model_dump() if hasattr(final_profile["personality"], 'model_dump') else dict(final_profile["personality"])
+            disposition_dict = final_profile["disposition"].model_dump() if hasattr(final_profile["disposition"], 'model_dump') else dict(final_profile["disposition"])
             return BankProfileResponse(
                 bank_id=bank_id,
                 name=final_profile["name"],
-                personality=PersonalityTraits(**personality_dict),
+                disposition=DispositionTraits(**disposition_dict),
                 background=final_profile["background"]
             )
         except Exception as e:
@@ -1852,11 +1852,11 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/memories",
         response_model=DeleteResponse,
         summary="Clear memory bank memories",
-        description="Delete memory units for a memory bank. Optionally filter by type (world, agent, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (personality and background) will be preserved.",
+        description="Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (personality and background) will be preserved.",
         operation_id="clear_bank_memories"
     )
     async def api_clear_bank_memories(bank_id: str,
-        type: Optional[str] = Query(None, description="Optional fact type filter (world, agent, opinion)")
+        type: Optional[str] = Query(None, description="Optional fact type filter (world, experience, opinion)")
     ):
         """Clear memories for a memory bank, optionally filtered by type."""
         try:

hindsight_api/api/mcp.py

@@ -90,7 +90,7 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
             search_result = await memory.recall_async(
                 bank_id=bank_id,
                 query=query,
-                fact_type=["world", "bank", "opinion"],
+                fact_type=["world", "experience", "opinion"],
                 budget=Budget.LOW
             )
 

hindsight_api/engine/llm_wrapper.py

@@ -6,6 +6,9 @@ import time
 import asyncio
 from typing import Optional, Any, Dict, List
 from openai import AsyncOpenAI, RateLimitError, APIError, APIStatusError, LengthFinishReasonError
+from google import genai
+from google.genai import types as genai_types
+from google.genai import errors as genai_errors
 import logging
 
 logger = logging.getLogger(__name__)
@@ -53,9 +56,9 @@ class LLMConfig:
         self.model = model
 
         # Validate provider
-        if self.provider not in ["openai", "groq", "ollama"]:
+        if self.provider not in ["openai", "groq", "ollama", "gemini"]:
             raise ValueError(
-                f"Invalid LLM provider: {self.provider}. Must be 'openai', 'groq', or 'ollama'."
+                f"Invalid LLM provider: {self.provider}. Must be 'openai', 'groq', 'ollama', or 'gemini'."
             )
 
         # Set default base URLs
@@ -66,19 +69,25 @@ class LLMConfig:
                 self.base_url = "http://localhost:11434/v1"
 
         # Validate API key (not needed for ollama)
-        if self.provider != "ollama" and not self.api_key:
+        if self.provider not in ["ollama"] and not self.api_key:
             raise ValueError(
                 f"API key not found for {self.provider}"
             )
 
         # Create client (private - use .call() method instead)
         # Disable automatic retries - we handle retries in the call() method
-        if self.provider == "ollama":
+        if self.provider == "gemini":
+            self._gemini_client = genai.Client(api_key=self.api_key)
+            self._client = None  # Not used for Gemini
+        elif self.provider == "ollama":
             self._client = AsyncOpenAI(api_key="ollama", base_url=self.base_url, max_retries=0)
+            self._gemini_client = None
         elif self.base_url:
             self._client = AsyncOpenAI(api_key=self.api_key, base_url=self.base_url, max_retries=0)
+            self._gemini_client = None
         else:
             self._client = AsyncOpenAI(api_key=self.api_key, max_retries=0)
+            self._gemini_client = None
 
         logger.info(
             f"Initialized LLM: provider={self.provider}, model={self.model}, base_url={self.base_url}"
@@ -116,6 +125,11 @@ class LLMConfig:
         # Use global semaphore to limit concurrent requests
         async with _global_llm_semaphore:
             start_time = time.time()
+            import json
+
+            # Handle Gemini provider separately
+            if self.provider == "gemini":
+                return await self._call_gemini(messages, response_format, max_retries, initial_backoff, max_backoff, skip_validation, start_time, **kwargs)
 
             call_params = {
                 "model": self.model,
@@ -137,7 +151,6 @@ class LLMConfig:
                     if response_format is not None:
                         # Use JSON mode instead of strict parse for flexibility with optional fields
                         # This allows the LLM to omit optional fields without validation errors
-                        import json
 
                         # Add schema to the system message
                         if hasattr(response_format, 'model_json_schema'):
@@ -215,6 +228,128 @@ class LLMConfig:
                 raise last_exception
             raise RuntimeError(f"LLM call failed after all retries with no exception captured")
 
+    async def _call_gemini(
+        self,
+        messages: List[Dict[str, str]],
+        response_format: Optional[Any],
+        max_retries: int,
+        initial_backoff: float,
+        max_backoff: float,
+        skip_validation: bool,
+        start_time: float,
+        **kwargs
+    ) -> Any:
+        """Handle Gemini-specific API calls using google-genai SDK."""
+        import json
+
+        # Convert OpenAI-style messages to Gemini format
+        # Gemini uses 'user' and 'model' roles, and system instructions are separate
+        system_instruction = None
+        gemini_contents = []
+
+        for msg in messages:
+            role = msg.get('role', 'user')
+            content = msg.get('content', '')
+
+            if role == 'system':
+                # Accumulate system messages as system instruction
+                if system_instruction:
+                    system_instruction += "\n\n" + content
+                else:
+                    system_instruction = content
+            elif role == 'assistant':
+                gemini_contents.append(genai_types.Content(
+                    role="model",
+                    parts=[genai_types.Part(text=content)]
+                ))
+            else:  # user or any other role
+                gemini_contents.append(genai_types.Content(
+                    role="user",
+                    parts=[genai_types.Part(text=content)]
+                ))
+
+        # Add JSON schema instruction if response_format is provided
+        if response_format is not None and hasattr(response_format, 'model_json_schema'):
+            schema = response_format.model_json_schema()
+            schema_msg = f"\n\nYou must respond with valid JSON matching this schema:\n{json.dumps(schema, indent=2)}"
+            if system_instruction:
+                system_instruction += schema_msg
+            else:
+                system_instruction = schema_msg
+
+        # Build generation config
+        config_kwargs = {}
+        if system_instruction:
+            config_kwargs['system_instruction'] = system_instruction
+        if 'temperature' in kwargs:
+            config_kwargs['temperature'] = kwargs['temperature']
+        if 'max_tokens' in kwargs:
+            config_kwargs['max_output_tokens'] = kwargs['max_tokens']
+        if response_format is not None:
+            config_kwargs['response_mime_type'] = 'application/json'
+
+        generation_config = genai_types.GenerateContentConfig(**config_kwargs) if config_kwargs else None
+
+        last_exception = None
+
+        for attempt in range(max_retries + 1):
+            try:
+                response = await self._gemini_client.aio.models.generate_content(
+                    model=self.model,
+                    contents=gemini_contents,
+                    config=generation_config,
+                )
+
+                content = response.text
+
+                if response_format is not None:
+                    # Parse the JSON response
+                    json_data = json.loads(content)
+
+                    # Return raw JSON if skip_validation is True, otherwise validate with Pydantic
+                    if skip_validation:
+                        result = json_data
+                    else:
+                        result = response_format.model_validate(json_data)
+                else:
+                    result = content
+
+                # Log call details only if it takes more than 10 seconds
+                duration = time.time() - start_time
+                if duration > 10.0 and hasattr(response, 'usage_metadata') and response.usage_metadata:
+                    usage = response.usage_metadata
+                    logger.info(
+                        f"slow llm call: model={self.provider}/{self.model}, "
+                        f"input_tokens={usage.prompt_token_count}, output_tokens={usage.candidates_token_count}, "
+                        f"time={duration:.3f}s"
+                    )
+
+                return result
+
+            except genai_errors.APIError as e:
+                # Handle rate limits and server errors with retry
+                if e.code in (429, 503, 500):
+                    last_exception = e
+                    if attempt < max_retries:
+                        backoff = min(initial_backoff * (2 ** attempt), max_backoff)
+                        jitter = backoff * 0.2 * (2 * (time.time() % 1) - 1)
+                        sleep_time = backoff + jitter
+                        await asyncio.sleep(sleep_time)
+                    else:
+                        logger.error(f"Gemini API error after {max_retries + 1} attempts: {str(e)}")
+                        raise
+                else:
+                    logger.error(f"Gemini API error: {type(e).__name__}: {str(e)}")
+                    raise
+
+            except Exception as e:
+                logger.error(f"Unexpected error during Gemini call: {type(e).__name__}: {str(e)}")
+                raise
+
+        if last_exception:
+            raise last_exception
+        raise RuntimeError(f"Gemini call failed after all retries with no exception captured")
+
     @classmethod
     def for_memory(cls) -> "LLMConfig":
         """Create configuration for memory operations from environment variables."""