x-ipe 1.0.23__py3-none-any.whl → 1.0.25__py3-none-any.whl

x_ipe/templates/knowledge-base.html

@@ -0,0 +1,110 @@
+{% extends "base.html" %}
+
+{% block title %}Knowledge Base - X-IPE{% endblock %}
+
+{% block body %}
+<div class="app-container">
+    <!-- ROW 1: Top Bar -->
+    <header class="top-bar">
+        <div class="d-flex align-items-center gap-3">
+            <a href="/" class="top-bar-brand text-decoration-none">
+                <i class="bi bi-journal-code me-2"></i>X-IPE
+            </a>
+            <nav aria-label="breadcrumb" class="top-bar-breadcrumb">
+                <ol class="breadcrumb mb-0" id="breadcrumb">
+                    <li class="breadcrumb-item active">Knowledge Base</li>
+                </ol>
+            </nav>
+        </div>
+        <div class="d-flex align-items-center gap-2">
+            <button class="btn btn-sm btn-primary" id="btn-refresh-index" title="Refresh index">
+                <i class="bi bi-arrow-clockwise"></i> Refresh
+            </button>
+            <a href="/settings" class="btn btn-link text-light" title="Settings">
+                <i class="bi bi-gear-fill"></i>
+            </a>
+        </div>
+    </header>
+
+    <!-- ROW 2: Middle Section (sidebar + content) -->
+    <div class="middle-section" id="middle-section">
+        <!-- LEFT: Sidebar Navigation -->
+        <nav class="sidebar" id="sidebar">
+            <!-- Search Box -->
+            <div class="kb-sidebar-search p-2">
+                <input type="text" class="form-control form-control-sm" id="kb-search" 
+                       placeholder="Search files..." aria-label="Search knowledge base">
+            </div>
+            <!-- File Tree -->
+            <div class="sidebar-content" id="sidebar-content">
+                <div class="loading-spinner">
+                    <div class="spinner-border spinner-border-sm text-light" role="status">
+                        <span class="visually-hidden">Loading...</span>
+                    </div>
+                </div>
+            </div>
+        </nav>
+        
+        <!-- Resize Handle -->
+        <div class="sidebar-resize-handle" id="sidebar-resize-handle"></div>
+    
+        <!-- RIGHT: Content Area -->
+        <main class="content-area">
+            <div class="content-view" id="content-view">
+                <div class="content-header d-flex justify-content-between align-items-center" id="content-header">
+                    <h5 class="mb-0" id="content-title">Knowledge Base</h5>
+                    <div class="kb-stats" id="kb-stats">
+                        <!-- File count, topic count loaded here -->
+                    </div>
+                </div>
+                <div class="content-body" id="content-body">
+                    <!-- KB content loaded here -->
+                    <div class="kb-landing-view" id="kb-landing-view">
+                        <div class="kb-section">
+                            <h6><i class="bi bi-inbox me-2"></i>Landing (Unprocessed)</h6>
+                            <div class="kb-file-list" id="landing-files">
+                                <p class="text-muted small">No files in landing folder</p>
+                            </div>
+                        </div>
+                        <div class="kb-section mt-4">
+                            <h6><i class="bi bi-folder me-2"></i>Topics</h6>
+                            <div class="kb-topics-grid" id="topics-grid">
+                                <p class="text-muted small">No topics created yet</p>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </main>
+    </div>
+    
+    <!-- ROW 3: Footer Terminal Panel -->
+    <div class="terminal-panel" id="terminal-panel">
+        <div class="terminal-header">
+            <div class="terminal-tabs" id="terminal-tabs">
+                <!-- Tabs rendered by JavaScript -->
+            </div>
+            <div class="d-flex align-items-center gap-2">
+                <button class="btn btn-sm btn-outline-light" id="btn-new-terminal" title="New Terminal">
+                    <i class="bi bi-plus"></i>
+                </button>
+                <button class="btn btn-sm btn-outline-light terminal-toggle" id="terminal-toggle" title="Toggle Terminal">
+                    <i class="bi bi-chevron-down"></i>
+                </button>
+            </div>
+        </div>
+        <div class="terminal-body" id="terminal-body">
+            <!-- xterm.js terminals rendered here -->
+        </div>
+    </div>
+</div>
+
+<script>
+// Auto-initialize KB view when page loads
+document.addEventListener('DOMContentLoaded', function() {
+    if (window.kbCore) {
+        window.kbCore.init();
+    }
+});
+</script>
+{% endblock %}

x_ipe/templates/workplace.html

@@ -21,6 +21,10 @@
             <button class="btn btn-sm btn-primary" id="btn-create-idea" title="Create new idea">
                 <i class="bi bi-plus-lg"></i> Create Idea
             </button>
+            <!-- FEATURE-025-A: Knowledge Base Button -->
+            <button class="btn btn-sm btn-outline-secondary" id="btn-knowledge-base" title="Knowledge Base">
+                <i class="bi bi-archive"></i>
+            </button>
             <!-- FEATURE-011: Stage Toolbox Button -->
             <button class="btn btn-sm btn-outline-secondary" id="btn-stage-toolbox" title="Stage Toolbox">
                 <i class="bi bi-tools"></i>

x_ipe/tracing/__init__.py

@@ -0,0 +1,37 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+Tracing module for X-IPE applications.
+
+Provides automatic function tracing with sensitive data redaction,
+execution timing, and structured log output.
+
+Usage:
+    from x_ipe.tracing import x_ipe_tracing, TraceContext
+
+    @x_ipe_tracing(level="INFO", redact=["password"])
+    def my_function(email: str, password: str):
+        ...
+
+    # Start/end traces manually (usually done by middleware)
+    TraceContext.start_trace("POST /api/endpoint")
+    # ... execute traced functions ...
+    buffer = TraceContext.end_trace()
+"""
+
+from .decorator import x_ipe_tracing
+from .context import TraceContext
+from .buffer import TraceBuffer, TraceEntry
+from .writer import TraceLogWriter
+from .redactor import Redactor
+from .middleware import init_tracing_middleware
+
+__all__ = [
+    'x_ipe_tracing',
+    'TraceContext',
+    'TraceBuffer',
+    'TraceEntry',
+    'TraceLogWriter',
+    'Redactor',
+    'init_tracing_middleware',
+]

x_ipe/tracing/buffer.py

@@ -0,0 +1,135 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+TraceBuffer and TraceEntry for in-memory trace storage.
+
+Traces are collected in-memory during request execution and flushed
+to log files upon request completion.
+"""
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import List, Optional, Any
+import json
+
+
+@dataclass
+class TraceEntry:
+    """
+    Single trace log entry representing a function call event.
+    
+    Attributes:
+        timestamp: When the event occurred
+        trace_id: Unique identifier for the trace
+        level: Log level (INFO, DEBUG, ERROR)
+        direction: Arrow direction (→ for entry, ← for exit)
+        event_type: Type of event (start_function, return_function, exception)
+        function_name: Name of the traced function
+        data: Parameters, return value, or error details
+        duration_ms: Execution time in milliseconds (only for exit events)
+        depth: Nesting level (0 = root)
+    """
+    timestamp: datetime
+    trace_id: str
+    level: str
+    direction: str
+    event_type: str
+    function_name: str
+    data: dict
+    duration_ms: Optional[float] = None
+    depth: int = 0
+
+
+class TraceBuffer:
+    """
+    In-memory buffer for trace entries during request execution.
+    
+    Collects trace entries and formats them for log file output.
+    Enforces a maximum size limit to prevent memory exhaustion.
+    
+    Usage:
+        buffer = TraceBuffer("abc-123", "POST /api/orders")
+        buffer.add(TraceEntry(...))
+        log_content = buffer.to_log_string("SUCCESS", 150.0)
+    """
+    
+    MAX_SIZE = 10 * 1024 * 1024  # 10MB limit
+    
+    def __init__(self, trace_id: str, root_api: str):
+        """
+        Initialize TraceBuffer.
+        
+        Args:
+            trace_id: Unique identifier for this trace
+            root_api: The root API call (e.g., "POST /api/orders")
+        """
+        self.trace_id = trace_id
+        self.root_api = root_api
+        self.started_at = datetime.now(timezone.utc)
+        self.entries: List[TraceEntry] = []
+        self._size = 0
+    
+    def add(self, entry: TraceEntry) -> None:
+        """
+        Add a trace entry to the buffer.
+        
+        Silently drops entries if buffer size limit is exceeded.
+        
+        Args:
+            entry: TraceEntry to add
+        """
+        try:
+            entry_size = len(json.dumps(entry.data, default=str))
+        except (TypeError, ValueError):
+            entry_size = 100  # Fallback size estimate
+        
+        if self._size + entry_size > self.MAX_SIZE:
+            return  # Silently drop if buffer full
+        
+        self.entries.append(entry)
+        self._size += entry_size
+    
+    def to_log_string(self, status: str, total_ms: float) -> str:
+        """
+        Format the buffer as a log file string.
+        
+        Args:
+            status: Final status (SUCCESS, ERROR)
+            total_ms: Total execution time in milliseconds
+            
+        Returns:
+            Formatted log string ready for file output
+        """
+        lines = [
+            f"[TRACE-START] {self.trace_id} | {self.root_api} | {self.started_at.isoformat()}Z"
+        ]
+        
+        for entry in self.entries:
+            indent = "  " * (entry.depth + 1)
+            
+            try:
+                data_str = json.dumps(entry.data, default=str, ensure_ascii=False)
+            except (TypeError, ValueError):
+                data_str = str(entry.data)
+            
+            # Truncate very long data
+            if len(data_str) > 1000:
+                data_str = data_str[:997] + "..."
+            
+            if entry.duration_ms is not None:
+                line = (
+                    f"{indent}[{entry.level}] {entry.direction} {entry.event_type}: "
+                    f"{entry.function_name} | {data_str} | {entry.duration_ms:.0f}ms"
+                )
+            else:
+                line = (
+                    f"{indent}[{entry.level}] {entry.direction} {entry.event_type}: "
+                    f"{entry.function_name} | {data_str}"
+                )
+            
+            lines.append(line)
+        
+        lines.append(
+            f"[TRACE-END] {self.trace_id} | {total_ms:.0f}ms | {status}"
+        )
+        
+        return "\n".join(lines)

x_ipe/tracing/context.py

@@ -0,0 +1,125 @@
+"""
+FEATURE-023: Application Action Tracing - Core
+
+TraceContext for thread-safe context propagation using contextvars.
+
+Manages the active trace context across nested function calls,
+ensuring trace ID propagation and proper nesting depth tracking.
+"""
+from contextvars import ContextVar
+from typing import Optional, List
+import uuid
+
+from .buffer import TraceBuffer
+
+
+# Thread-safe context variable for the active trace
+_trace_context: ContextVar[Optional['TraceContext']] = ContextVar(
+    'trace_context', 
+    default=None
+)
+
+
+class TraceContext:
+    """
+    Thread-safe trace context manager.
+    
+    Uses Python's contextvars to maintain trace state across async
+    function calls. Tracks trace ID, buffer, and call depth.
+    
+    Usage:
+        # Start a new trace
+        ctx = TraceContext.start_trace("POST /api/orders")
+        
+        # Get current context (in nested calls)
+        ctx = TraceContext.get_current()
+        
+        # End trace and get buffer
+        buffer = TraceContext.end_trace()
+    """
+    
+    def __init__(self, trace_id: str, root_api: str):
+        """
+        Initialize TraceContext.
+        
+        Args:
+            trace_id: Unique identifier for this trace
+            root_api: The root API call (e.g., "POST /api/orders")
+        """
+        self.trace_id = trace_id
+        self.buffer = TraceBuffer(trace_id, root_api)
+        self.depth = 0
+        self._call_stack: List[str] = []
+    
+    @classmethod
+    def start_trace(cls, root_api: str) -> 'TraceContext':
+        """
+        Start a new trace.
+        
+        Generates a unique trace ID and creates a new context.
+        Sets the context as the active trace.
+        
+        Args:
+            root_api: The root API call (e.g., "POST /api/orders")
+            
+        Returns:
+            New TraceContext instance
+        """
+        # Generate short UUID for readability (first 13 chars)
+        trace_id = str(uuid.uuid4())[:13]
+        ctx = cls(trace_id, root_api)
+        _trace_context.set(ctx)
+        return ctx
+    
+    @classmethod
+    def get_current(cls) -> Optional['TraceContext']:
+        """
+        Get the current active trace context.
+        
+        Returns:
+            Active TraceContext or None if no trace is active
+        """
+        return _trace_context.get()
+    
+    @classmethod
+    def end_trace(cls) -> Optional[TraceBuffer]:
+        """
+        End the current trace and return the buffer.
+        
+        Clears the active context.
+        
+        Returns:
+            TraceBuffer containing all trace entries, or None if no active trace
+        """
+        ctx = _trace_context.get()
+        if ctx:
+            _trace_context.set(None)
+            return ctx.buffer
+        return None
+    
+    def push_call(self, func_name: str) -> int:
+        """
+        Push a function call onto the stack.
+        
+        Increments depth and tracks the function name.
+        
+        Args:
+            func_name: Name of the function being called
+            
+        Returns:
+            Depth level before increment (for logging)
+        """
+        self._call_stack.append(func_name)
+        depth = self.depth
+        self.depth += 1
+        return depth
+    
+    def pop_call(self) -> None:
+        """
+        Pop a function call from the stack.
+        
+        Decrements depth and removes the function from tracking.
+        """
+        if self._call_stack:
+            self._call_stack.pop()
+            self.depth -= 1