hindsight-api 0.0.14__py3-none-any.whl → 0.0.16__py3-none-any.whl

hindsight_api/cli.py

@@ -0,0 +1,128 @@
+"""
+Command-line interface for Hindsight API.
+
+Run the server with:
+    hindsight-api
+
+Stop with Ctrl+C.
+"""
+import argparse
+import asyncio
+import atexit
+import os
+import signal
+import sys
+from typing import Optional
+
+import uvicorn
+
+from . import MemoryEngine
+from .api import create_app
+
+
+# Disable tokenizers parallelism to avoid warnings
+os.environ["TOKENIZERS_PARALLELISM"] = "false"
+
+# Global reference for cleanup
+_memory: Optional[MemoryEngine] = None
+
+
+def _cleanup():
+    """Synchronous cleanup function to stop resources on exit."""
+    global _memory
+    if _memory is not None and _memory._pg0 is not None:
+        try:
+            loop = asyncio.new_event_loop()
+            loop.run_until_complete(_memory._pg0.stop())
+            loop.close()
+            print("\npg0 stopped.")
+        except Exception as e:
+            print(f"\nError stopping pg0: {e}")
+
+
+def _signal_handler(signum, frame):
+    """Handle SIGINT/SIGTERM to ensure cleanup."""
+    print(f"\nReceived signal {signum}, shutting down...")
+    _cleanup()
+    sys.exit(0)
+
+
+def main():
+    """Main entry point for the CLI."""
+    global _memory
+
+    parser = argparse.ArgumentParser(
+        prog="hindsight-api",
+        description="Hindsight API Server",
+    )
+    parser.add_argument(
+        "--host", default="0.0.0.0",
+        help="Host to bind to (default: 0.0.0.0)"
+    )
+    parser.add_argument(
+        "--port", type=int, default=8888,
+        help="Port to bind to (default: 8888)"
+    )
+    parser.add_argument(
+        "--log-level", default="info",
+        choices=["critical", "error", "warning", "info", "debug", "trace"],
+        help="Log level (default: info)"
+    )
+    parser.add_argument(
+        "--access-log", action="store_true",
+        help="Enable access log"
+    )
+
+    args = parser.parse_args()
+
+    # Register cleanup handlers
+    atexit.register(_cleanup)
+    signal.signal(signal.SIGINT, _signal_handler)
+    signal.signal(signal.SIGTERM, _signal_handler)
+
+    # Get configuration from environment variables
+    db_url = os.getenv("HINDSIGHT_API_DATABASE_URL", "pg0")
+    llm_provider = os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq")
+    llm_api_key = os.getenv("HINDSIGHT_API_LLM_API_KEY", "")
+    llm_model = os.getenv("HINDSIGHT_API_LLM_MODEL", "openai/gpt-oss-20b")
+    llm_base_url = os.getenv("HINDSIGHT_API_LLM_BASE_URL") or None
+
+    # Create MemoryEngine
+    _memory = MemoryEngine(
+        db_url=db_url,
+        memory_llm_provider=llm_provider,
+        memory_llm_api_key=llm_api_key,
+        memory_llm_model=llm_model,
+        memory_llm_base_url=llm_base_url,
+    )
+
+    # Create FastAPI app
+    app = create_app(
+        memory=_memory,
+        http_api_enabled=True,
+        mcp_api_enabled=True,
+        mcp_mount_path="/mcp",
+        run_migrations=True,
+        initialize_memory=True,
+    )
+
+    # Prepare uvicorn config
+    uvicorn_config = {
+        "app": app,
+        "host": args.host,
+        "port": args.port,
+        "log_level": args.log_level,
+        "access_log": args.access_log,
+    }
+
+    print(f"\nStarting Hindsight API...")
+    print(f"  URL: http://{args.host}:{args.port}")
+    print(f"  Database: {db_url}")
+    print(f"  LLM Provider: {llm_provider}")
+    print()
+
+    uvicorn.run(**uvicorn_config)
+
+
+if __name__ == "__main__":
+    main()

hindsight_api/engine/retain/fact_extraction.py

@@ -16,6 +16,24 @@ from pydantic import BaseModel, Field, field_validator, ConfigDict
 from ..llm_wrapper import OutputTooLongError, LLMConfig
 
 
+def _sanitize_text(text: str) -> str:
+    """
+    Sanitize text by removing invalid Unicode surrogate characters.
+
+    Surrogate characters (U+D800 to U+DFFF) are used in UTF-16 encoding
+    but cannot be encoded in UTF-8. They can appear in Python strings
+    from improperly decoded data (e.g., from JavaScript or broken files).
+
+    This function removes unpaired surrogates to prevent UnicodeEncodeError
+    when the text is sent to the LLM API.
+    """
+    if not text:
+        return text
+    # Remove surrogate characters (U+D800 to U+DFFF) using regex
+    # These are invalid in UTF-8 and cause encoding errors
+    return re.sub(r'[\ud800-\udfff]', '', text)
+
+
 class Entity(BaseModel):
     """An entity extracted from text."""
     text: str = Field(
@@ -470,6 +488,10 @@ WHAT TO EXTRACT vs SKIP
     max_retries = 2
     last_error = None
 
+    # Sanitize input text to prevent Unicode encoding errors (e.g., unpaired surrogates)
+    sanitized_chunk = _sanitize_text(chunk)
+    sanitized_context = _sanitize_text(context) if context else 'none'
+
     # Build user message with metadata and chunk content in a clear format
     # Format event_date with day of week for better temporal reasoning
     event_date_formatted = event_date.strftime('%A, %B %d, %Y')  # e.g., "Monday, June 10, 2024"
@@ -477,10 +499,10 @@ WHAT TO EXTRACT vs SKIP
 
 Chunk: {chunk_index + 1}/{total_chunks}
 Event Date: {event_date_formatted} ({event_date.isoformat()})
-Context: {context if context else 'none'}
+Context: {sanitized_context}
 
 Text:
-{chunk}"""
+{sanitized_chunk}"""
 
     for attempt in range(max_retries):
         try:

hindsight_api/web/server.py

@@ -85,7 +85,7 @@ if __name__ == "__main__":
         env_log_level = "info"
 
     # Parse CLI arguments
-    parser = argparse.ArgumentParser(description="Memory Graph API Server")
+    parser = argparse.ArgumentParser(description="Hindsight API Server")
     parser.add_argument("--host", default="0.0.0.0", help="Host to bind to (default: 0.0.0.0)")
     parser.add_argument("--port", type=int, default=8888, help="Port to bind to (default: 8888)")
     parser.add_argument("--reload", action="store_true", help="Enable auto-reload on code changes")

{hindsight_api-0.0.14.dist-info → hindsight_api-0.0.16.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hindsight-api
-Version: 0.0.14
+Version: 0.0.16
 Summary: Temporal + Semantic + Entity Memory System for AI agents using PostgreSQL
 Requires-Python: >=3.11
 Requires-Dist: alembic>=1.17.1

{hindsight_api-0.0.14.dist-info → hindsight_api-0.0.16.dist-info}/RECORD

@@ -1,4 +1,5 @@
 hindsight_api/__init__.py,sha256=yQWYWUWEhvs1OY1coENhZV_CuOAWmN_YKZXQMIvGN94,851
+hindsight_api/cli.py,sha256=-dxAHsET_pHd6NlA3ufI4KEKQA3fL3YapCvDB_x2ax8,3303
 hindsight_api/metrics.py,sha256=j4-eeqVjjcGQxAxS_GgEaBNm10KdUxrGS_I2d1IM1hY,7255
 hindsight_api/migrations.py,sha256=VY-ILJLWEY1IaeJgQ2jlAVUtPLzq_41Dytg_DjuF0GA,6402
 hindsight_api/models.py,sha256=1vMn9jmDQvohfmxZXr1SYnhz5vhz52nrTd93A_lkVNE,12606
@@ -24,7 +25,7 @@ hindsight_api/engine/retain/deduplication.py,sha256=9YXgVI_m1Mtz5Cv46ZceCEs0GwpL
 hindsight_api/engine/retain/embedding_processing.py,sha256=cHTt3rPvDCWBWVPfSeg6bwH8HoXYGmP4bvS21boNONI,1734
 hindsight_api/engine/retain/embedding_utils.py,sha256=Q24h_iw6pRAW2vDWPvauWY1o3bXLzW3eWvSxDALDiE0,1588
 hindsight_api/engine/retain/entity_processing.py,sha256=meHOjsFzdvh1tbe6YlTofhcUs2Y6TcAN3S-0EKOvFP0,2705
-hindsight_api/engine/retain/fact_extraction.py,sha256=D7nnDn7U0UhsAwbo9qahPSpGxiRP-L5tdHT1JAIKM44,45254
+hindsight_api/engine/retain/fact_extraction.py,sha256=vOIlag9rJ8_8Q-TfOhMY88PeJpUyFIp0i7vdEyzbJLY,46125
 hindsight_api/engine/retain/fact_storage.py,sha256=gRRQf_FCLsj5lUvdlOaxJsS5JosM6IhO_pik8Ur8VFg,5717
 hindsight_api/engine/retain/link_creation.py,sha256=XJx7U3HboJLHtGgt_tHGsCa58lGo2ZyywzMNosrY9Xc,3154
 hindsight_api/engine/retain/link_utils.py,sha256=PAXalIhAPZGcJv8EugcpwNgoWZ2D_ciVU3brHL-m090,26226
@@ -42,7 +43,8 @@ hindsight_api/engine/search/trace.py,sha256=GT86_LVKMyG2mw6EJzPjafvbqaot6XVy5fZ0
 hindsight_api/engine/search/tracer.py,sha256=mcM9qZpj3YFudrBCESwc6YKNAiWIMx1lScXWn5ru-ok,15017
 hindsight_api/engine/search/types.py,sha256=qIeHW_gT7f291vteTZXygAM8oAaPp2dq6uEdvOyOwzs,5488
 hindsight_api/web/__init__.py,sha256=WABqyqiAVFJJWOhKCytkj5Vcb61eAsRib3Ek7IMX6_U,378
-hindsight_api/web/server.py,sha256=oPNJ_z4DO38MdK7Juyh2LdH0ipZ_BQF48cUM-4B_Uw0,5379
-hindsight_api-0.0.14.dist-info/METADATA,sha256=FFYSGyrGsxR_vYmM11h2AK4pqC8MdbOjjV46yJ0mlL8,1496
-hindsight_api-0.0.14.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-hindsight_api-0.0.14.dist-info/RECORD,,
+hindsight_api/web/server.py,sha256=txP1OBiwxZTyDbPLUYZ9XPMysskxEceHlxbDEvIq0ok,5376
+hindsight_api-0.0.16.dist-info/METADATA,sha256=0Tg86KkYkFYEBFBGjUhSE-RwllDeQ5n30vctTeK2DFk,1496
+hindsight_api-0.0.16.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+hindsight_api-0.0.16.dist-info/entry_points.txt,sha256=53Fn-VxtkqreZhOPTJB_FupH7e5GyiMY3gzEp22d8xs,57
+hindsight_api-0.0.16.dist-info/RECORD,,

hindsight_api-0.0.16.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hindsight-api = hindsight_api.cli:main