sentrial 0.1.2__tar.gz

sentrial-0.1.2/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Sentrial
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

sentrial-0.1.2/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md
+include LICENSE
+include py.typed
+recursive-include sentrial *.py
+recursive-include sentrial py.typed
+

sentrial-0.1.2/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: sentrial
+Version: 0.1.2
+Summary: Sentrial - Observability and time-travel debugging for AI agents
+Author-email: Sentrial Team <support@sentrial.ai>
+License: MIT
+Project-URL: Homepage, https://sentrial.app
+Project-URL: Documentation, https://docs.sentrial.app
+Project-URL: Repository, https://github.com/neelshar/sentrial
+Project-URL: Bug Tracker, https://github.com/neelshar/sentrial/issues
+Keywords: ai,agents,observability,debugging,langchain,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: langchain>=0.1.0; extra == "all"
+Dynamic: license-file
+
+# Sentrial Python SDK
+
+Observability and time-travel debugging for AI agents. Track every decision, tool call, and state change in your agent workflows.
+
+## Features
+
+- **Automatic Tracking**: Capture agent reasoning, tool calls, and state changes
+- **Git-like Branching**: Fork agent sessions at any point
+- **Time Travel**: Replay and debug past agent executions
+- **Framework Agnostic**: Works with LangChain, custom agents, and more
+- **Visual UI**: Beautiful web interface to explore agent behavior
+
+## Installation
+
+### From PyPI
+
+```bash
+# Standard installation
+pip install sentrial
+
+# With LangChain integration
+pip install sentrial[langchain]
+
+# All integrations
+pip install sentrial[all]
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/neelshar/Sentrial.git#subdirectory=packages/python-sdk
+```
+
+### Local Development
+
+```bash
+cd packages/python-sdk
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from sentrial import SentrialClient
+
+# Initialize client
+client = SentrialClient(
+    api_url="https://api.sentrial.app",  # Or your self-hosted URL
+    project_id="your-project-id"
+)
+
+# Create a session
+session_id = client.create_session(name="Customer Support Agent")
+
+# Track tool calls
+client.track_tool_call(
+    session_id=session_id,
+    tool_name="search_knowledge_base",
+    tool_input={"query": "password reset"},
+    tool_output={"articles": ["KB-001", "KB-002"]},
+    reasoning="Searching for relevant articles"
+)
+
+# Track LLM decisions
+client.track_decision(
+    session_id=session_id,
+    reasoning="User already tried KB solutions. Escalating to human support.",
+    alternatives=["Try another KB article", "Ask for more info"],
+    confidence=0.85
+)
+
+# Close session
+client.close_session(session_id)
+```
+
+### LangChain Integration
+
+```python
+from sentrial import SentrialClient, SentrialCallbackHandler
+from langchain.agents import AgentExecutor, create_react_agent
+
+# Initialize Sentrial
+client = SentrialClient(api_url="...", project_id="...")
+session_id = client.create_session(name="LangChain Agent")
+
+# Create callback handler
+handler = SentrialCallbackHandler(client, session_id, verbose=True)
+
+# Use with LangChain - automatic tracking!
+agent_executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    callbacks=[handler],  # ← That's it!
+    verbose=True
+)
+
+result = agent_executor.invoke({"input": "Help user with login issue"})
+```
+
+The callback handler automatically tracks:
+- Agent reasoning (Chain of Thought)
+- Tool calls (inputs & outputs)
+- Tool errors
+- Agent completion
+
+## Examples
+
+- [simple_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/simple_agent.py) - Basic agent tracking
+- [langchain_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/langchain_agent.py) - Full LangChain integration
+
+## Documentation
+
+- [Getting Started](https://sentrial.app/docs/quickstart)
+- [API Reference](https://sentrial.app/docs/api/auth)
+- [LangChain Integration](https://sentrial.app/docs/integrations/langchain)
+
+## Support
+
+- Email: support@sentrial.ai
+- Discord: [Join our community](https://discord.gg/sentrial)
+- Issues: [GitHub Issues](https://github.com/neelshar/Sentrial/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

sentrial-0.1.2/README.md

@@ -0,0 +1,128 @@
+# Sentrial Python SDK
+
+Observability and time-travel debugging for AI agents. Track every decision, tool call, and state change in your agent workflows.
+
+## Features
+
+- **Automatic Tracking**: Capture agent reasoning, tool calls, and state changes
+- **Git-like Branching**: Fork agent sessions at any point
+- **Time Travel**: Replay and debug past agent executions
+- **Framework Agnostic**: Works with LangChain, custom agents, and more
+- **Visual UI**: Beautiful web interface to explore agent behavior
+
+## Installation
+
+### From PyPI
+
+```bash
+# Standard installation
+pip install sentrial
+
+# With LangChain integration
+pip install sentrial[langchain]
+
+# All integrations
+pip install sentrial[all]
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/neelshar/Sentrial.git#subdirectory=packages/python-sdk
+```
+
+### Local Development
+
+```bash
+cd packages/python-sdk
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from sentrial import SentrialClient
+
+# Initialize client
+client = SentrialClient(
+    api_url="https://api.sentrial.app",  # Or your self-hosted URL
+    project_id="your-project-id"
+)
+
+# Create a session
+session_id = client.create_session(name="Customer Support Agent")
+
+# Track tool calls
+client.track_tool_call(
+    session_id=session_id,
+    tool_name="search_knowledge_base",
+    tool_input={"query": "password reset"},
+    tool_output={"articles": ["KB-001", "KB-002"]},
+    reasoning="Searching for relevant articles"
+)
+
+# Track LLM decisions
+client.track_decision(
+    session_id=session_id,
+    reasoning="User already tried KB solutions. Escalating to human support.",
+    alternatives=["Try another KB article", "Ask for more info"],
+    confidence=0.85
+)
+
+# Close session
+client.close_session(session_id)
+```
+
+### LangChain Integration
+
+```python
+from sentrial import SentrialClient, SentrialCallbackHandler
+from langchain.agents import AgentExecutor, create_react_agent
+
+# Initialize Sentrial
+client = SentrialClient(api_url="...", project_id="...")
+session_id = client.create_session(name="LangChain Agent")
+
+# Create callback handler
+handler = SentrialCallbackHandler(client, session_id, verbose=True)
+
+# Use with LangChain - automatic tracking!
+agent_executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    callbacks=[handler],  # ← That's it!
+    verbose=True
+)
+
+result = agent_executor.invoke({"input": "Help user with login issue"})
+```
+
+The callback handler automatically tracks:
+- Agent reasoning (Chain of Thought)
+- Tool calls (inputs & outputs)
+- Tool errors
+- Agent completion
+
+## Examples
+
+- [simple_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/simple_agent.py) - Basic agent tracking
+- [langchain_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/langchain_agent.py) - Full LangChain integration
+
+## Documentation
+
+- [Getting Started](https://sentrial.app/docs/quickstart)
+- [API Reference](https://sentrial.app/docs/api/auth)
+- [LangChain Integration](https://sentrial.app/docs/integrations/langchain)
+
+## Support
+
+- Email: support@sentrial.ai
+- Discord: [Join our community](https://discord.gg/sentrial)
+- Issues: [GitHub Issues](https://github.com/neelshar/Sentrial/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

sentrial-0.1.2/pyproject.toml

@@ -0,0 +1,72 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sentrial"
+version = "0.1.2"
+description = "Sentrial - Observability and time-travel debugging for AI agents"
+readme = "README.md"
+authors = [
+    {name = "Sentrial Team", email = "support@sentrial.ai"}
+]
+license = {text = "MIT"}
+keywords = ["ai", "agents", "observability", "debugging", "langchain", "llm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.31.0",
+]
+
+[project.optional-dependencies]
+langchain = [
+    "langchain>=0.1.0",
+]
+dev = [
+    "pytest>=7.4.0",
+    "black>=23.0.0",
+    "mypy>=1.5.0",
+    "ruff>=0.1.0",
+]
+all = [
+    "langchain>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://sentrial.app"
+Documentation = "https://docs.sentrial.app"
+Repository = "https://github.com/neelshar/sentrial"
+"Bug Tracker" = "https://github.com/neelshar/sentrial/issues"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["sentrial*"]
+
+[tool.setuptools.package-data]
+sentrial = ["py.typed"]
+
+[tool.black]
+line-length = 100
+target-version = ["py38", "py39", "py310", "py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.mypy]
+python_version = "3.8"
+strict = true
+warn_return_any = true
+warn_unused_configs = true

sentrial-0.1.2/sentrial/__init__.py

@@ -0,0 +1,19 @@
+"""
+Sentrial Python SDK
+
+Simple SDK for tracking agent events and sending them to Sentrial.
+"""
+
+from .client import SentrialClient
+from .types import EventType
+
+__version__ = "0.1.2"
+__all__ = ["SentrialClient", "EventType"]
+
+# Optional LangChain integration (only available if langchain is installed)
+try:
+    from .langchain import SentrialCallbackHandler
+    __all__.append("SentrialCallbackHandler")
+except ImportError:
+    # LangChain not installed, skip
+    pass

sentrial-0.1.2/sentrial/client.py

@@ -0,0 +1,191 @@
+"""Sentrial Client - Main SDK interface"""
+
+import requests
+from typing import Any, Optional
+from .types import EventType
+
+
+class SentrialClient:
+    """
+    Sentrial Client for tracking agent events.
+
+    Usage:
+        client = SentrialClient(
+            api_url="http://localhost:3001",
+            project_id="your-project-id"
+        )
+
+        # Create a session
+        session_id = client.create_session(name="My Agent Run")
+
+        # Track events
+        client.track_tool_call(
+            session_id=session_id,
+            tool_name="search",
+            tool_input={"query": "test"},
+            tool_output={"result": "success"}
+        )
+
+        # Close session
+        client.close_session(session_id)
+    """
+
+    def __init__(
+        self,
+        api_url: str = "http://localhost:3001",
+        project_id: str = "00000000-0000-0000-0000-000000000000",
+        api_key: Optional[str] = None,
+    ):
+        """
+        Initialize Sentrial client.
+
+        Args:
+            api_url: URL of the Sentrial API server
+            project_id: Project ID (get from Sentrial dashboard)
+            api_key: API key for authentication
+        """
+        self.api_url = api_url.rstrip("/")
+        self.project_id = project_id
+        self.api_key = api_key
+        self.session = requests.Session()
+        self.current_state: dict[str, Any] = {}
+
+        if api_key:
+            self.session.headers.update({"Authorization": f"Bearer {api_key}"})
+
+    def create_session(
+        self,
+        name: str,
+        branch_name: str = "main",
+        metadata: Optional[dict[str, Any]] = None,
+    ) -> str:
+        """
+        Create a new session.
+
+        Args:
+            name: Name of the session
+            branch_name: Branch name (default: "main")
+            metadata: Optional metadata
+
+        Returns:
+            Session ID
+        """
+        response = self.session.post(
+            f"{self.api_url}/api/sdk/sessions",
+            json={
+                "projectId": self.project_id,
+                "name": name,
+                "branchName": branch_name,
+                "metadata": metadata,
+            },
+        )
+        response.raise_for_status()
+        data = response.json()
+        return data["id"]
+
+    def track_tool_call(
+        self,
+        session_id: str,
+        tool_name: str,
+        tool_input: dict[str, Any],
+        tool_output: dict[str, Any],
+        reasoning: Optional[str] = None,
+        branch_name: str = "main",
+    ) -> dict[str, Any]:
+        """
+        Track a tool call event.
+
+        Args:
+            session_id: Session ID
+            tool_name: Name of the tool
+            tool_input: Tool input data
+            tool_output: Tool output data
+            reasoning: Optional reasoning
+            branch_name: Branch name (default: "main")
+
+        Returns:
+            Event data
+        """
+        state_before = self.current_state.copy()
+
+        # Update current state (simplified)
+        self.current_state[f"{tool_name}_result"] = tool_output
+
+        response = self.session.post(
+            f"{self.api_url}/api/sdk/events",
+            json={
+                "sessionId": session_id,
+                "eventType": EventType.TOOL_CALL.value,
+                "toolName": tool_name,
+                "toolInput": tool_input,
+                "toolOutput": tool_output,
+                "reasoning": reasoning,
+                "stateBefore": state_before,
+                "stateAfter": self.current_state.copy(),
+                "branchName": branch_name,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def track_decision(
+        self,
+        session_id: str,
+        reasoning: str,
+        alternatives: Optional[list[str]] = None,
+        confidence: Optional[float] = None,
+        branch_name: str = "main",
+    ) -> dict[str, Any]:
+        """
+        Track an LLM decision event.
+
+        Args:
+            session_id: Session ID
+            reasoning: Decision reasoning
+            alternatives: Alternative options considered
+            confidence: Confidence score (0.0 to 1.0)
+            branch_name: Branch name (default: "main")
+
+        Returns:
+            Event data
+        """
+        state_before = self.current_state.copy()
+
+        response = self.session.post(
+            f"{self.api_url}/api/sdk/events",
+            json={
+                "sessionId": session_id,
+                "eventType": EventType.LLM_DECISION.value,
+                "reasoning": reasoning,
+                "alternativesConsidered": alternatives,
+                "confidence": confidence,
+                "stateBefore": state_before,
+                "stateAfter": self.current_state.copy(),
+                "branchName": branch_name,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+
+    def update_state(self, key: str, value: Any):
+        """Update the current state."""
+        self.current_state[key] = value
+
+    def close_session(self, session_id: str, duration_ms: Optional[int] = None):
+        """
+        Mark a session as completed.
+
+        Args:
+            session_id: Session ID
+            duration_ms: Duration in milliseconds
+        """
+        response = self.session.patch(
+            f"{self.api_url}/api/sdk/sessions/{session_id}",
+            json={
+                "status": "completed",
+                "durationMs": duration_ms,
+            },
+        )
+        response.raise_for_status()
+        return response.json()
+

sentrial-0.1.2/sentrial/langchain.py

@@ -0,0 +1,354 @@
+"""LangChain integration for Sentrial observability."""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+try:
+    from langchain_core.callbacks.base import BaseCallbackHandler
+    from langchain_core.agents import AgentAction, AgentFinish
+    from langchain_core.outputs import LLMResult
+except ImportError:
+    raise ImportError(
+        "LangChain is required for this integration. "
+        "Install it with: pip install langchain-core"
+    )
+
+from .client import SentrialClient
+
+
+class SentrialCallbackHandler(BaseCallbackHandler):
+    """
+    LangChain callback handler for Sentrial observability.
+    
+    Automatically tracks:
+    - Agent reasoning (Chain of Thought)
+    - Tool executions (with inputs/outputs)
+    - Tool errors
+    - LLM calls
+    
+    Usage:
+        from sentrial import SentrialClient
+        from sentrial.langchain import SentrialCallbackHandler
+        
+        client = SentrialClient(api_url="...", project_id="...")
+        session_id = client.create_session(name="My Agent")
+        
+        handler = SentrialCallbackHandler(client, session_id)
+        
+        # Pass to LangChain agent
+        agent_executor = AgentExecutor(
+            agent=agent,
+            tools=tools,
+            callbacks=[handler],
+            verbose=True
+        )
+    """
+    
+    def __init__(
+        self, 
+        client: SentrialClient, 
+        session_id: str,
+        track_llm_calls: bool = False,
+        verbose: bool = False
+    ):
+        """
+        Initialize Sentrial callback handler.
+        
+        Args:
+            client: SentrialClient instance
+            session_id: Active session ID
+            track_llm_calls: Whether to track individual LLM API calls (default: False)
+            verbose: Print tracking info (default: False)
+        """
+        super().__init__()
+        self.client = client
+        self.session_id = session_id
+        self.track_llm_calls = track_llm_calls
+        self.verbose = verbose
+        
+        # Track tool runs in flight (run_id -> tool data)
+        self.tool_runs: Dict[str, Dict[str, Any]] = {}
+        
+        # Track pending agent actions (for correlating with tool outputs)
+        self.pending_actions: Dict[str, Dict[str, Any]] = {}
+        
+        # Track agent steps
+        self.step_count = 0
+    
+    def _log(self, message: str):
+        """Log if verbose mode is enabled."""
+        if self.verbose:
+            print(f"[Sentrial] {message}")
+    
+    # ===== Agent Reasoning (Chain of Thought) =====
+    
+    def on_agent_action(
+        self, 
+        action: AgentAction, 
+        *, 
+        run_id: UUID, 
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """
+        Capture agent reasoning (Chain of Thought) and tool calls.
+        
+        This is called when the agent decides what action to take.
+        The action.log contains the full "Thought: ... Action: ..." trace.
+        
+        For agents that don't trigger on_tool_start/on_tool_end separately
+        (like function-calling agents or Gemini), we track the tool call here.
+        """
+        self.step_count += 1
+        reasoning = action.log if action.log else f"Action: {action.tool}"
+        tool_name = action.tool
+        tool_input = action.tool_input
+        
+        self._log(f"Step {self.step_count}: Agent action - {tool_name}")
+        
+        # Store the pending action for correlation with tool output (if on_tool_end fires)
+        self.pending_actions[str(run_id)] = {
+            "tool": tool_name,
+            "input": tool_input,
+            "reasoning": reasoning,
+            "tracked": False  # Will be set to True if we track from on_tool_end
+        }
+        
+        # Track as tool_call with the available info
+        # This ensures tools are tracked even if on_tool_start/on_tool_end don't fire
+        input_dict = tool_input if isinstance(tool_input, dict) else {"input": str(tool_input) if tool_input else ""}
+        
+        self.client.track_tool_call(
+            session_id=self.session_id,
+            tool_name=tool_name,
+            tool_input=input_dict,
+            tool_output={"status": "executed"},  # Placeholder, updated if on_tool_end fires
+            reasoning=reasoning
+        )
+        
+        # Mark as tracked so on_tool_end doesn't duplicate
+        self.pending_actions[str(run_id)]["tracked"] = True
+    
+    def on_agent_finish(
+        self,
+        finish: AgentFinish,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track agent completion."""
+        self._log("Agent finished")
+        
+        self.client.track_decision(
+            session_id=self.session_id,
+            reasoning=f"Agent completed: {finish.return_values.get('output', 'No output')}",
+            confidence=1.0
+        )
+    
+    # ===== Tool Execution =====
+    
+    def on_tool_start(
+        self,
+        serialized: Dict[str, Any],
+        input_str: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Buffer tool inputs for correlation with outputs."""
+        tool_name = serialized.get("name", "unknown_tool")
+        
+        self._log(f"Tool started: {tool_name}")
+        
+        # Check if we have a pending action for this tool from on_agent_action
+        parent_id = str(parent_run_id) if parent_run_id else None
+        pending = None
+        if parent_id and parent_id in self.pending_actions:
+            pending = self.pending_actions.get(parent_id)
+        
+        self.tool_runs[str(run_id)] = {
+            "name": tool_name,
+            "input": input_str,
+            "pending_action": pending,
+            "parent_run_id": parent_id
+        }
+    
+    def on_tool_end(
+        self,
+        output: str,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track successful tool execution with full input/output."""
+        run_data = self.tool_runs.pop(str(run_id), None)
+        
+        # Check if this was already tracked from on_agent_action
+        parent_id = str(parent_run_id) if parent_run_id else None
+        if parent_id and parent_id in self.pending_actions:
+            pending = self.pending_actions[parent_id]
+            if pending.get("tracked"):
+                # Already tracked from on_agent_action, just log
+                self._log(f"Tool output received: {pending['tool']} (already tracked)")
+                del self.pending_actions[parent_id]
+                return
+        
+        if run_data:
+            self._log(f"Tool completed: {run_data['name']}")
+            
+            # Parse tool input - try to get structured data
+            tool_input = run_data.get("input", "")
+            if isinstance(tool_input, str):
+                # Try to parse as JSON
+                import json
+                try:
+                    tool_input = json.loads(tool_input)
+                except (json.JSONDecodeError, TypeError):
+                    tool_input = {"input": tool_input}
+            
+            # Parse tool output
+            tool_output = output
+            if isinstance(tool_output, str):
+                import json
+                try:
+                    tool_output = json.loads(tool_output)
+                except (json.JSONDecodeError, TypeError):
+                    tool_output = {"output": tool_output}
+            
+            # Get reasoning from pending action if available
+            pending = run_data.get("pending_action")
+            reasoning = pending.get("reasoning") if pending else f"Executed {run_data['name']}"
+            
+            self.client.track_tool_call(
+                session_id=self.session_id,
+                tool_name=run_data["name"],
+                tool_input=tool_input if isinstance(tool_input, dict) else {"input": tool_input},
+                tool_output=tool_output if isinstance(tool_output, dict) else {"output": tool_output},
+                reasoning=reasoning
+            )
+            
+            # Clean up pending action if we had one
+            parent_id = run_data.get("parent_run_id")
+            if parent_id and parent_id in self.pending_actions:
+                del self.pending_actions[parent_id]
+        else:
+            self._log(f"Tool completed but no start event found (run_id: {run_id})")
+    
+    def on_tool_error(
+        self,
+        error: Exception,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track tool failures."""
+        run_data = self.tool_runs.pop(str(run_id), None)
+        
+        if run_data:
+            self._log(f"Tool failed: {run_data['name']} - {str(error)}")
+            
+            self.client.track_tool_call(
+                session_id=self.session_id,
+                tool_name=run_data["name"],
+                tool_input={"input": run_data["input"]},
+                tool_output={"error": str(error), "error_type": type(error).__name__},
+                reasoning=f"Tool execution failed: {str(error)}"
+            )
+        else:
+            self._log(f"Tool failed but no start event found (run_id: {run_id})")
+    
+    # ===== LLM Calls (Optional) =====
+    
+    def on_llm_start(
+        self,
+        serialized: Dict[str, Any],
+        prompts: List[str],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track LLM API calls (if enabled)."""
+        if not self.track_llm_calls:
+            return
+        
+        model_name = serialized.get("name", "unknown_model")
+        self._log(f"LLM call started: {model_name}")
+    
+    def on_llm_end(
+        self,
+        response: LLMResult,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track LLM completion (if enabled)."""
+        if not self.track_llm_calls:
+            return
+        
+        self._log("LLM call completed")
+        
+        # Could track as a special event type if needed
+        # For now, we focus on agent-level reasoning and tools
+    
+    def on_llm_error(
+        self,
+        error: Exception,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track LLM errors (if enabled)."""
+        if not self.track_llm_calls:
+            return
+        
+        self._log(f"LLM call failed: {str(error)}")
+    
+    # ===== Chain Events (Optional, for future use) =====
+    
+    def on_chain_start(
+        self,
+        serialized: Dict[str, Any],
+        inputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track chain execution start."""
+        pass  # Can be used for more granular tracking if needed
+    
+    def on_chain_end(
+        self,
+        outputs: Dict[str, Any],
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track chain execution end."""
+        pass  # Can be used for more granular tracking if needed
+    
+    def on_chain_error(
+        self,
+        error: Exception,
+        *,
+        run_id: UUID,
+        parent_run_id: Optional[UUID] = None,
+        **kwargs: Any
+    ) -> None:
+        """Track chain execution errors."""
+        self._log(f"Chain failed: {str(error)}")
+        
+        self.client.track_decision(
+            session_id=self.session_id,
+            reasoning=f"Chain execution failed: {str(error)}",
+            confidence=0.0
+        )
+

sentrial-0.1.2/sentrial/types.py

@@ -0,0 +1,44 @@
+"""Type definitions for Sentrial SDK"""
+
+from enum import Enum
+from typing import Any, Optional, TypedDict
+
+
+class EventType(str, Enum):
+    """Event types"""
+
+    TOOL_CALL = "tool_call"
+    LLM_DECISION = "llm_decision"
+    STATE_CHANGE = "state_change"
+    ERROR = "error"
+
+
+class ToolCallEvent(TypedDict, total=False):
+    """Tool call event data"""
+
+    session_id: str
+    event_type: str
+    tool_name: str
+    tool_input: dict[str, Any]
+    tool_output: dict[str, Any]
+    tool_error: Optional[dict[str, Any]]
+    reasoning: Optional[str]
+    state_before: Optional[dict[str, Any]]
+    state_after: Optional[dict[str, Any]]
+    branch_name: str
+    metadata: Optional[dict[str, Any]]
+
+
+class DecisionEvent(TypedDict, total=False):
+    """LLM decision event data"""
+
+    session_id: str
+    event_type: str
+    reasoning: str
+    alternatives_considered: Optional[list[str]]
+    confidence: Optional[float]
+    state_before: Optional[dict[str, Any]]
+    state_after: Optional[dict[str, Any]]
+    branch_name: str
+    metadata: Optional[dict[str, Any]]
+

sentrial-0.1.2/sentrial.egg-info/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: sentrial
+Version: 0.1.2
+Summary: Sentrial - Observability and time-travel debugging for AI agents
+Author-email: Sentrial Team <support@sentrial.ai>
+License: MIT
+Project-URL: Homepage, https://sentrial.app
+Project-URL: Documentation, https://docs.sentrial.app
+Project-URL: Repository, https://github.com/neelshar/sentrial
+Project-URL: Bug Tracker, https://github.com/neelshar/sentrial/issues
+Keywords: ai,agents,observability,debugging,langchain,llm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: langchain
+Requires-Dist: langchain>=0.1.0; extra == "langchain"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: all
+Requires-Dist: langchain>=0.1.0; extra == "all"
+Dynamic: license-file
+
+# Sentrial Python SDK
+
+Observability and time-travel debugging for AI agents. Track every decision, tool call, and state change in your agent workflows.
+
+## Features
+
+- **Automatic Tracking**: Capture agent reasoning, tool calls, and state changes
+- **Git-like Branching**: Fork agent sessions at any point
+- **Time Travel**: Replay and debug past agent executions
+- **Framework Agnostic**: Works with LangChain, custom agents, and more
+- **Visual UI**: Beautiful web interface to explore agent behavior
+
+## Installation
+
+### From PyPI
+
+```bash
+# Standard installation
+pip install sentrial
+
+# With LangChain integration
+pip install sentrial[langchain]
+
+# All integrations
+pip install sentrial[all]
+```
+
+### From GitHub
+
+```bash
+pip install git+https://github.com/neelshar/Sentrial.git#subdirectory=packages/python-sdk
+```
+
+### Local Development
+
+```bash
+cd packages/python-sdk
+pip install -e .
+```
+
+## Quick Start
+
+### Basic Usage
+
+```python
+from sentrial import SentrialClient
+
+# Initialize client
+client = SentrialClient(
+    api_url="https://api.sentrial.app",  # Or your self-hosted URL
+    project_id="your-project-id"
+)
+
+# Create a session
+session_id = client.create_session(name="Customer Support Agent")
+
+# Track tool calls
+client.track_tool_call(
+    session_id=session_id,
+    tool_name="search_knowledge_base",
+    tool_input={"query": "password reset"},
+    tool_output={"articles": ["KB-001", "KB-002"]},
+    reasoning="Searching for relevant articles"
+)
+
+# Track LLM decisions
+client.track_decision(
+    session_id=session_id,
+    reasoning="User already tried KB solutions. Escalating to human support.",
+    alternatives=["Try another KB article", "Ask for more info"],
+    confidence=0.85
+)
+
+# Close session
+client.close_session(session_id)
+```
+
+### LangChain Integration
+
+```python
+from sentrial import SentrialClient, SentrialCallbackHandler
+from langchain.agents import AgentExecutor, create_react_agent
+
+# Initialize Sentrial
+client = SentrialClient(api_url="...", project_id="...")
+session_id = client.create_session(name="LangChain Agent")
+
+# Create callback handler
+handler = SentrialCallbackHandler(client, session_id, verbose=True)
+
+# Use with LangChain - automatic tracking!
+agent_executor = AgentExecutor(
+    agent=agent,
+    tools=tools,
+    callbacks=[handler],  # ← That's it!
+    verbose=True
+)
+
+result = agent_executor.invoke({"input": "Help user with login issue"})
+```
+
+The callback handler automatically tracks:
+- Agent reasoning (Chain of Thought)
+- Tool calls (inputs & outputs)
+- Tool errors
+- Agent completion
+
+## Examples
+
+- [simple_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/simple_agent.py) - Basic agent tracking
+- [langchain_agent.py](https://github.com/neelshar/Sentrial/blob/main/examples/langchain_agent.py) - Full LangChain integration
+
+## Documentation
+
+- [Getting Started](https://sentrial.app/docs/quickstart)
+- [API Reference](https://sentrial.app/docs/api/auth)
+- [LangChain Integration](https://sentrial.app/docs/integrations/langchain)
+
+## Support
+
+- Email: support@sentrial.ai
+- Discord: [Join our community](https://discord.gg/sentrial)
+- Issues: [GitHub Issues](https://github.com/neelshar/Sentrial/issues)
+
+## License
+
+MIT License - see [LICENSE](LICENSE) for details.
+

sentrial-0.1.2/sentrial.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+MANIFEST.in
+README.md
+py.typed
+pyproject.toml
+sentrial/__init__.py
+sentrial/client.py
+sentrial/langchain.py
+sentrial/types.py
+sentrial.egg-info/PKG-INFO
+sentrial.egg-info/SOURCES.txt
+sentrial.egg-info/dependency_links.txt
+sentrial.egg-info/requires.txt
+sentrial.egg-info/top_level.txt

sentrial-0.1.2/sentrial.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sentrial-0.1.2/sentrial.egg-info/requires.txt

@@ -0,0 +1,13 @@
+requests>=2.31.0
+
+[all]
+langchain>=0.1.0
+
+[dev]
+pytest>=7.4.0
+black>=23.0.0
+mypy>=1.5.0
+ruff>=0.1.0
+
+[langchain]
+langchain>=0.1.0

sentrial-0.1.2/sentrial.egg-info/top_level.txt

@@ -0,0 +1 @@
+sentrial

sentrial-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+