gateforge-sdk 0.2.3__tar.gz → 0.2.5__tar.gz

{gateforge_sdk-0.2.3 → gateforge_sdk-0.2.5}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: gateforge-sdk
-Version: 0.2.3
-Summary: Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session tracing, PII masking, cost tracking
+Version: 0.2.5
+Summary: Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support
 Project-URL: Homepage, https://gateforge.dev
 Project-URL: Documentation, https://gateforge.dev/docs
 Project-URL: Repository, https://github.com/gateforge/gateforge-sdk

{gateforge_sdk-0.2.3 → gateforge_sdk-0.2.5}/gateforge/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.2.5"
 
 # Auto-install spaCy model if missing (required for PII detection)
 def _ensure_spacy_model():
@@ -26,6 +26,15 @@ from gateforge.response import GatforgeResponse
 from gateforge.tracing import configure_otel
 from gateforge.ab.engine import VariantAssignment
 from gateforge.guardrails.engine import GuardrailViolation, GuardrailBlocked
+from gateforge.session_manager import (
+    SessionManager,
+    SessionState,
+    get_session_manager,
+    create_session,
+    get_session,
+    get_current_conversation_id,
+    get_current_trace_info,
+)
 
 _client: GatforgeClient | None = None
 
@@ -426,6 +435,14 @@ __all__ = [
     "agent",
     "record_tool_call",
     "record_tool_result",
+    # Session management (Phase 2)
+    "SessionManager",
+    "SessionState",
+    "get_session_manager",
+    "create_session",
+    "get_session",
+    "get_current_conversation_id",
+    "get_current_trace_info",
     # OTel configuration
     "configure_otel",
     # Standalone PII helpers

{gateforge_sdk-0.2.3 → gateforge_sdk-0.2.5}/gateforge/context.py

@@ -183,6 +183,9 @@ def agent(
     """
     Decorator that creates a trace context for an agent function.
     
+    If there's an active trace (e.g., from gateforge.session()), it uses that
+    conversation_id for proper nesting. Otherwise creates a new trace.
+    
     All LLM calls and tool calls inside are automatically traced.
     
     Usage::
@@ -190,14 +193,27 @@ def agent(
         def my_agent(message):
             response = client.chat.completions.create(...)
             return response
+        
+        # Or inside a session - shares the session's conversation_id:
+        with gateforge.session() as sess:
+            my_agent("hello")  # Uses sess.conversation_id
     """
     def decorator(fn: Callable) -> Callable:
         @functools.wraps(fn)
         def wrapper(*args: Any, **kwargs: Any) -> Any:
             from gateforge.tracing import emit_trace_event
             
-            # Generate or use provided conversation_id
-            cid = conversation_id or f"{fn.__name__}-{int(time.time())}"
+            # Check if there's an active trace (e.g., from session())
+            active_trace = get_active_trace()
+            
+            if active_trace:
+                # Use existing conversation_id for nesting
+                cid = active_trace.conversation_id
+                is_nested = True
+            else:
+                # Create new conversation_id
+                cid = conversation_id or f"{fn.__name__}-{int(time.time())}"
+                is_nested = False
             
             # Emit agent start event
             emit_trace_event(
@@ -206,12 +222,15 @@ def agent(
                 conversation_id=cid,
                 event_type="agent_start",
                 step=0,
-                metadata={"user_id": user_id, "args": _safe_str(args)[:200], "agent_name": name or fn.__name__},
+                metadata={"user_id": user_id, "args": _safe_str(args)[:200], "agent_name": name or fn.__name__, "nested": is_nested},
             )
             
-            # Enter trace context
-            ctx = trace(conversation_id=cid)
-            ctx.__enter__()
+            # Enter trace context (only if not already in one)
+            if not is_nested:
+                ctx = trace(conversation_id=cid)
+                ctx.__enter__()
+            else:
+                ctx = None  # Already in a trace context
             
             try:
                 result = fn(*args, **kwargs)
@@ -222,7 +241,7 @@ def agent(
                     base_url=_get_base_url(),
                     conversation_id=cid,
                     event_type="agent_end",
-                    step=ctx.ctx.step,
+                    step=active_trace.step if active_trace else ctx.ctx.step,
                     metadata={"success": True},
                 )
                 
@@ -234,12 +253,13 @@ def agent(
                     base_url=_get_base_url(),
                     conversation_id=cid,
                     event_type="agent_error",
-                    step=ctx.ctx.step,
+                    step=active_trace.step if active_trace else ctx.ctx.step,
                     metadata={"error": str(e)[:500]},
                 )
                 raise
             finally:
-                ctx.__exit__(None, None, None)
+                if ctx:
+                    ctx.__exit__(None, None, None)
         
         return wrapper
     return decorator

gateforge_sdk-0.2.5/gateforge/session_manager.py

@@ -0,0 +1,344 @@
+"""
+Phase 2: Session Management & Enhanced Trace Context
+
+Provides:
+- SessionManager for persistent session state
+- Enhanced metadata support (user_id, tags, custom fields)
+- Session persistence (save/load from dict)
+- Conversation helpers
+"""
+
+from __future__ import annotations
+
+import uuid
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+
+
+@dataclass
+class SessionState:
+    """
+    Represents the state of a conversation session.
+    
+    Attributes:
+        conversation_id: Unique identifier for the conversation
+        user_id: Optional user identifier
+        created_at: Unix timestamp when session was created
+        updated_at: Unix timestamp of last activity
+        message_count: Number of messages/turns in this conversation
+        tags: Optional tags for categorization
+        metadata: Custom metadata dictionary
+    """
+    conversation_id: str
+    user_id: Optional[str] = None
+    created_at: float = field(default_factory=time.time)
+    updated_at: float = field(default_factory=time.time)
+    message_count: int = 0
+    tags: List[str] = field(default_factory=list)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize session state to dictionary."""
+        return {
+            "conversation_id": self.conversation_id,
+            "user_id": self.user_id,
+            "created_at": self.created_at,
+            "updated_at": self.updated_at,
+            "message_count": self.message_count,
+            "tags": self.tags,
+            "metadata": self.metadata,
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SessionState:
+        """Deserialize session state from dictionary."""
+        return cls(
+            conversation_id=data["conversation_id"],
+            user_id=data.get("user_id"),
+            created_at=data.get("created_at", time.time()),
+            updated_at=data.get("updated_at", time.time()),
+            message_count=data.get("message_count", 0),
+            tags=data.get("tags", []),
+            metadata=data.get("metadata", {}),
+        )
+    
+    def touch(self) -> None:
+        """Update the updated_at timestamp and increment message count."""
+        self.updated_at = time.time()
+        self.message_count += 1
+    
+    def add_tag(self, tag: str) -> None:
+        """Add a tag to the session."""
+        if tag not in self.tags:
+            self.tags.append(tag)
+    
+    def set_metadata(self, key: str, value: Any) -> None:
+        """Set a metadata field."""
+        self.metadata[key] = value
+
+
+class SessionManager:
+    """
+    Manages conversation sessions with persistence support.
+    
+    Usage::
+        # Create manager
+        manager = SessionManager()
+        
+        # Create new session
+        session = manager.create_session(user_id="user-123")
+        print(session.conversation_id)
+        
+        # Get existing session
+        session = manager.get_session("conv-123")
+        
+        # Update session activity
+        manager.touch("conv-123")
+        
+        # Serialize all sessions
+        data = manager.to_dict()
+        
+        # Load from serialized data
+        manager2 = SessionManager.from_dict(data)
+    """
+    
+    def __init__(self):
+        self._sessions: Dict[str, SessionState] = {}
+    
+    def create_session(
+        self,
+        user_id: Optional[str] = None,
+        conversation_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> SessionState:
+        """
+        Create a new session.
+        
+        Args:
+            user_id: Optional user identifier
+            conversation_id: Optional explicit conversation_id (auto-generated if not provided)
+            tags: Optional list of tags
+            metadata: Optional custom metadata
+        
+        Returns:
+            New SessionState object
+        """
+        cid = conversation_id or str(uuid.uuid4())
+        
+        session = SessionState(
+            conversation_id=cid,
+            user_id=user_id,
+            tags=tags or [],
+            metadata=metadata or {},
+        )
+        
+        self._sessions[cid] = session
+        return session
+    
+    def get_session(self, conversation_id: str) -> Optional[SessionState]:
+        """
+        Get an existing session by ID.
+        
+        Args:
+            conversation_id: The conversation ID to look up
+        
+        Returns:
+            SessionState if found, None otherwise
+        """
+        return self._sessions.get(conversation_id)
+    
+    def get_or_create_session(
+        self,
+        conversation_id: str,
+        user_id: Optional[str] = None,
+    ) -> SessionState:
+        """
+        Get existing session or create new one if not exists.
+        
+        Args:
+            conversation_id: The conversation ID
+            user_id: Optional user_id for new session
+        
+        Returns:
+            Existing or new SessionState
+        """
+        if conversation_id in self._sessions:
+            return self._sessions[conversation_id]
+        
+        return self.create_session(
+            conversation_id=conversation_id,
+            user_id=user_id,
+        )
+    
+    def touch(self, conversation_id: str) -> None:
+        """
+        Update session activity timestamp and message count.
+        
+        Args:
+            conversation_id: The conversation ID to touch
+        """
+        session = self._sessions.get(conversation_id)
+        if session:
+            session.touch()
+    
+    def delete_session(self, conversation_id: str) -> bool:
+        """
+        Delete a session.
+        
+        Args:
+            conversation_id: The conversation ID to delete
+        
+        Returns:
+            True if deleted, False if not found
+        """
+        if conversation_id in self._sessions:
+            del self._sessions[conversation_id]
+            return True
+        return False
+    
+    def list_sessions(
+        self,
+        user_id: Optional[str] = None,
+        tags: Optional[List[str]] = None,
+        limit: Optional[int] = None,
+    ) -> List[SessionState]:
+        """
+        List sessions with optional filters.
+        
+        Args:
+            user_id: Filter by user_id
+            tags: Filter by tags (must have all specified tags)
+            limit: Maximum number of sessions to return
+        
+        Returns:
+            List of matching SessionState objects
+        """
+        sessions = list(self._sessions.values())
+        
+        if user_id:
+            sessions = [s for s in sessions if s.user_id == user_id]
+        
+        if tags:
+            sessions = [s for s in sessions if all(tag in s.tags for tag in tags)]
+        
+        # Sort by updated_at (most recent first)
+        sessions.sort(key=lambda s: s.updated_at, reverse=True)
+        
+        if limit:
+            sessions = sessions[:limit]
+        
+        return sessions
+    
+    def to_dict(self) -> Dict[str, Any]:
+        """Serialize all sessions to dictionary."""
+        return {
+            "sessions": {
+                cid: session.to_dict()
+                for cid, session in self._sessions.items()
+            }
+        }
+    
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> SessionManager:
+        """Deserialize SessionManager from dictionary."""
+        manager = cls()
+        
+        sessions_data = data.get("sessions", {})
+        for cid, session_data in sessions_data.items():
+            manager._sessions[cid] = SessionState.from_dict(session_data)
+        
+        return manager
+    
+    def __len__(self) -> int:
+        """Return number of active sessions."""
+        return len(self._sessions)
+    
+    def __contains__(self, conversation_id: str) -> bool:
+        """Check if conversation_id exists."""
+        return conversation_id in self._sessions
+
+
+# ---------------------------------------------------------------------------
+# Global session manager (optional convenience)
+# ---------------------------------------------------------------------------
+
+_default_manager: Optional[SessionManager] = None
+
+
+def get_session_manager() -> SessionManager:
+    """Get or create the default session manager."""
+    global _default_manager
+    if _default_manager is None:
+        _default_manager = SessionManager()
+    return _default_manager
+
+
+def create_session(
+    user_id: Optional[str] = None,
+    conversation_id: Optional[str] = None,
+    tags: Optional[List[str]] = None,
+) -> SessionState:
+    """
+    Create a new session using the default manager.
+    
+    Usage::
+        session = gateforge.create_session(user_id="user-123")
+        print(session.conversation_id)
+    """
+    return get_session_manager().create_session(
+        user_id=user_id,
+        conversation_id=conversation_id,
+        tags=tags,
+    )
+
+
+def get_session(conversation_id: str) -> Optional[SessionState]:
+    """
+    Get an existing session using the default manager.
+    
+    Usage::
+        session = gateforge.get_session("conv-123")
+        if session:
+            print(f"Messages: {session.message_count}")
+    """
+    return get_session_manager().get_session(conversation_id)
+
+
+def get_current_conversation_id() -> Optional[str]:
+    """
+    Get the conversation_id from the active trace context.
+    
+    Usage::
+        cid = gateforge.get_current_conversation_id()
+        if cid:
+            print(f"Current conversation: {cid}")
+    """
+    from gateforge.context import get_active_trace
+    trace = get_active_trace()
+    return trace.conversation_id if trace else None
+
+
+def get_current_trace_info() -> Optional[Dict[str, Any]]:
+    """
+    Get information about the current trace context.
+    
+    Returns:
+        Dictionary with conversation_id, trace_id, step, or None if no active trace
+    
+    Usage::
+        info = gateforge.get_current_trace_info()
+        if info:
+            print(f"Conversation: {info['conversation_id']}, Step: {info['step']}")
+    """
+    from gateforge.context import get_active_trace
+    trace = get_active_trace()
+    if trace:
+        return {
+            "conversation_id": trace.conversation_id,
+            "trace_id": trace.trace_id,
+            "step": trace.step,
+        }
+    return None

{gateforge_sdk-0.2.3 → gateforge_sdk-0.2.5}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gateforge-sdk"
-version = "0.2.3"
-description = "Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session tracing, PII masking, cost tracking"
+version = "0.2.5"
+description = "Privacy-first LLMOps SDK — Auto-init, tool/agent decorators, session management, nested conversation support"
 readme = "README.md"
 license = { text = "MIT" }
 requires-python = ">=3.10"