cite-agent 1.0.0__py3-none-any.whl

cite_agent/__distribution__.py

@@ -0,0 +1,7 @@
+"""
+This is a DISTRIBUTION build.
+Local LLM calling code has been removed.
+All queries must go through the centralized backend.
+"""
+DISTRIBUTION_BUILD = True
+BACKEND_ONLY = True

cite_agent/__init__.py

@@ -0,0 +1,66 @@
+"""
+Nocturnal Archive - Beta Agent
+
+A Groq-powered research and finance co-pilot with deterministic tooling and
+prior stacks preserved only in Git history, kept out of the runtime footprint.
+"""
+
+from .enhanced_ai_agent import EnhancedNocturnalAgent, ChatRequest, ChatResponse
+
+__version__ = "0.9.0b1"
+__author__ = "Nocturnal Archive Team"
+__email__ = "contact@nocturnal.dev"
+
+__all__ = [
+    "EnhancedNocturnalAgent",
+    "ChatRequest", 
+    "ChatResponse"
+]
+
+# Package metadata
+PACKAGE_NAME = "nocturnal-archive"
+PACKAGE_VERSION = __version__
+PACKAGE_DESCRIPTION = "Beta CLI agent for finance + research workflows"
+PACKAGE_URL = "https://github.com/Spectating101/nocturnal-archive"
+
+def get_version():
+    """Get the package version"""
+    return __version__
+
+def quick_start():
+    """Print quick start instructions"""
+    print("""
+🚀 Nocturnal Archive Quick Start
+================================
+
+1. Install the package and CLI:
+   pip install nocturnal-archive
+
+2. Configure your Groq key:
+   nocturnal --setup
+
+3. Ask a question:
+   nocturnal "Compare Apple and Microsoft net income this quarter"
+
+4. Prefer embedding in code? Minimal example:
+   ```python
+   import asyncio
+   from nocturnal_archive import EnhancedNocturnalAgent, ChatRequest
+
+   async def main():
+       agent = EnhancedNocturnalAgent()
+       await agent.initialize()
+
+       response = await agent.process_request(ChatRequest(question="List repo workspace files"))
+       print(response.response)
+
+       await agent.close()
+
+   asyncio.run(main())
+   ```
+
+Full installation instructions live in docs/INSTALL.md.
+""")
+
+if __name__ == "__main__":
+    quick_start()

cite_agent/account_client.py

@@ -0,0 +1,130 @@
+"""Account provisioning utilities for the Nocturnal Archive CLI."""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+class AccountProvisioningError(RuntimeError):
+    """Raised when account provisioning fails."""
+
+
+@dataclass(frozen=True)
+class AccountCredentials:
+    """User account credentials for backend authentication.
+
+    Production mode: User gets JWT tokens, NOT API keys.
+    Backend has the API keys, user just authenticates with JWT.
+    """
+    account_id: str
+    email: str
+    auth_token: str  # JWT for backend authentication
+    refresh_token: str
+    telemetry_token: str
+    issued_at: Optional[str] = None
+
+    @classmethod
+    def from_payload(cls, email: str, payload: Dict[str, Any]) -> "AccountCredentials":
+        try:
+            return cls(
+                account_id=str(payload["accountId"]),
+                email=email,
+                auth_token=str(payload["authToken"]),
+                refresh_token=str(payload.get("refreshToken", "")),
+                telemetry_token=str(payload.get("telemetryToken", "")),
+                issued_at=str(payload.get("issuedAt", "")) or None,
+            )
+        except KeyError as exc:  # pragma: no cover - defensive guard
+            raise AccountProvisioningError(
+                f"Account provisioning payload missing field: {exc!s}"  # noqa: TRY200
+            ) from exc
+
+
+class AccountClient:
+    """Minimal client for authenticating against the control plane.
+
+    If ``NOCTURNAL_CONTROL_PLANE_URL`` is unset the client falls back to an
+    offline deterministic token generator so local development and CI remain
+    hermetic.
+    """
+
+    def __init__(self, base_url: Optional[str] = None, timeout: int = 10):
+        self.base_url = (
+            base_url
+            or os.getenv("NOCTURNAL_CONTROL_PLANE_URL")
+            or "https://cite-agent-api-720dfadd602c.herokuapp.com"
+        )
+        self.timeout = timeout
+
+    def provision(self, email: str, password: str) -> AccountCredentials:
+        if self.base_url:
+            payload = self._request_credentials(email, password)
+            return AccountCredentials.from_payload(email=email, payload=payload)
+        return self._generate_offline_credentials(email, password)
+
+    # -- internal helpers -------------------------------------------------
+    def _request_credentials(self, email: str, password: str) -> Dict[str, Any]:
+        try:  # pragma: no cover - requires network
+            import requests  # type: ignore
+        except Exception as exc:  # pragma: no cover - executed when requests missing
+            raise AccountProvisioningError(
+                "The 'requests' package is required for control-plane authentication"
+            ) from exc
+
+        endpoint = self.base_url.rstrip("/") + "/api/beta/login"
+        body = {"email": email, "password": password, "client": "cli"}
+        try:
+            response = requests.post(endpoint, json=body, timeout=self.timeout)
+        except Exception as exc:  # pragma: no cover - network failure
+            raise AccountProvisioningError("Failed to reach control plane") from exc
+
+        if response.status_code >= 400:
+            detail = self._extract_error_detail(response)
+            raise AccountProvisioningError(
+                f"Authentication failed (status {response.status_code}): {detail}"
+            )
+
+        try:
+            payload = response.json()
+        except ValueError as exc:  # pragma: no cover - invalid JSON
+            raise AccountProvisioningError("Control plane returned invalid JSON") from exc
+
+        if not isinstance(payload, dict):  # pragma: no cover - sanity guard
+            raise AccountProvisioningError("Control plane response must be an object")
+        return payload
+
+    @staticmethod
+    def _extract_error_detail(response: Any) -> str:
+        try:  # pragma: no cover - best effort decoding
+            data = response.json()
+            if isinstance(data, dict) and data.get("detail"):
+                return str(data["detail"])
+        except Exception:
+            pass
+        return response.text.strip() or "unknown error"
+
+    @staticmethod
+    def _generate_offline_credentials(email: str, password: str) -> AccountCredentials:
+        seed = f"{email.lower()}::{password}"
+        digest = hashlib.sha256(seed.encode("utf-8")).hexdigest()
+        auth_token = digest[12:44]
+        refresh_token = digest[44:]
+        telemetry_token = digest[24:56]
+        return AccountCredentials(
+            account_id=digest[:12],
+            email=email,
+            auth_token=auth_token,
+            refresh_token=refresh_token,
+            telemetry_token=telemetry_token,
+            issued_at=None,
+        )
+
+
+__all__ = [
+    "AccountClient",
+    "AccountCredentials",
+    "AccountProvisioningError",
+]

cite_agent/agent_backend_only.py

@@ -0,0 +1,172 @@
+"""
+Backend-Only Agent (Distribution Version)
+All LLM queries go through centralized backend API.
+Local API keys are not supported.
+"""
+
+import os
+import requests
+from typing import Dict, Any, Optional
+from dataclasses import dataclass
+from datetime import datetime, timezone
+
+@dataclass
+class ChatRequest:
+    question: str
+    user_id: str = "default"
+    conversation_id: str = "default"
+    context: Dict[str, Any] = None
+
+@dataclass
+class ChatResponse:
+    response: str
+    citations: list = None
+    tools_used: list = None
+    model: str = "backend"
+    timestamp: str = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.now(timezone.utc).isoformat()
+        if self.citations is None:
+            self.citations = []
+        if self.tools_used is None:
+            self.tools_used = []
+
+class EnhancedNocturnalAgent:
+    """
+    Backend-only agent for distribution.
+    Proxies all requests to centralized API.
+    """
+
+    def __init__(self):
+        self.backend_url = (
+            os.getenv("NOCTURNAL_CONTROL_PLANE_URL")
+            or "https://cite-agent-api-720dfadd602c.herokuapp.com"
+        )
+        self.auth_token = None
+        self._load_auth()
+
+    def _load_auth(self):
+        """Load authentication token from config"""
+        # Try environment first
+        self.auth_token = os.getenv("NOCTURNAL_AUTH_TOKEN")
+
+        # Try config file
+        if not self.auth_token:
+            from pathlib import Path
+            config_file = Path.home() / ".nocturnal_archive" / "config.env"
+            if config_file.exists():
+                with open(config_file) as f:
+                    for line in f:
+                        if line.startswith("NOCTURNAL_AUTH_TOKEN="):
+                            self.auth_token = line.split("=", 1)[1].strip()
+                            break
+
+    async def initialize(self):
+        """Initialize agent"""
+        if not self.auth_token:
+            raise RuntimeError(
+                "Not authenticated. Please run 'cite-agent --setup' first."
+            )
+        print(f"✅ Connected to backend: {self.backend_url}")
+
+    async def chat(self, request: ChatRequest) -> ChatResponse:
+        """
+        Send chat request to backend API.
+
+        Args:
+            request: Chat request with question and context
+
+        Returns:
+            Chat response with answer and citations
+
+        Raises:
+            RuntimeError: If authentication fails or backend unavailable
+        """
+        if not self.auth_token:
+            raise RuntimeError(
+                "Not authenticated. Run 'cite-agent --setup' first."
+            )
+
+        try:
+            response = requests.post(
+                f"{self.backend_url}/api/query",
+                headers={
+                    "Authorization": f"Bearer {self.auth_token}",
+                    "Content-Type": "application/json"
+                },
+                json={
+                    "query": request.question,
+                    "context": request.context or {},
+                    "user_id": request.user_id,
+                    "conversation_id": request.conversation_id,
+                },
+                timeout=60
+            )
+
+            if response.status_code == 401:
+                raise RuntimeError(
+                    "Authentication expired. Run 'cite-agent --setup' to log in again."
+                )
+
+            if response.status_code == 429:
+                raise RuntimeError(
+                    "Daily quota exceeded (25,000 tokens). Resets tomorrow."
+                )
+
+            if response.status_code >= 400:
+                error_detail = response.json().get("detail", response.text)
+                raise RuntimeError(f"Backend error: {error_detail}")
+
+            data = response.json()
+
+            return ChatResponse(
+                response=data.get("response", data.get("answer", "")),
+                citations=data.get("citations", []),
+                tools_used=data.get("tools_used", []),
+                model=data.get("model", "backend"),
+            )
+
+        except requests.RequestException as e:
+            raise RuntimeError(
+                f"Backend connection failed: {e}. Check your internet connection."
+            ) from e
+
+    async def close(self):
+        """Cleanup"""
+        pass
+
+    def get_health_status(self) -> Dict[str, Any]:
+        """Get backend health status"""
+        try:
+            response = requests.get(
+                f"{self.backend_url}/api/health/",
+                timeout=5
+            )
+            return response.json()
+        except:
+            return {"status": "unavailable"}
+
+    def check_quota(self) -> Dict[str, Any]:
+        """Check remaining daily quota"""
+        if not self.auth_token:
+            raise RuntimeError("Not authenticated")
+
+        response = requests.get(
+            f"{self.backend_url}/api/auth/me",
+            headers={"Authorization": f"Bearer {self.auth_token}"},
+            timeout=10
+        )
+
+        if response.status_code == 401:
+            raise RuntimeError("Authentication expired")
+
+        response.raise_for_status()
+        data = response.json()
+
+        return {
+            "tokens_used": data.get("tokens_used_today", 0),
+            "tokens_remaining": data.get("tokens_remaining", 0),
+            "daily_limit": 25000,
+        }

cite_agent/ascii_plotting.py

@@ -0,0 +1,296 @@
+#!/usr/bin/env python3
+"""
+ASCII Plotting Module for Terminal Visualization
+Uses plotext for clean, readable terminal charts
+"""
+
+import sys
+from typing import List, Optional, Dict, Any, Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Try to import plotext
+try:
+    import plotext as plt
+    PLOTEXT_AVAILABLE = True
+except ImportError:
+    PLOTEXT_AVAILABLE = False
+    logger.warning("plotext not installed - ASCII plotting unavailable")
+
+
+class ASCIIPlotter:
+    """
+    Terminal-based plotting using plotext
+    Generates clean ASCII charts for data visualization
+    """
+    
+    def __init__(self, width: int = 70, height: int = 20):
+        """
+        Initialize plotter
+        
+        Args:
+            width: Plot width in characters
+            height: Plot height in characters
+        """
+        self.width = width
+        self.height = height
+        self.available = PLOTEXT_AVAILABLE
+    
+    def plot_line(
+        self,
+        x: List[float],
+        y: List[float],
+        title: str = "Line Plot",
+        xlabel: str = "X",
+        ylabel: str = "Y",
+        label: Optional[str] = None
+    ) -> str:
+        """
+        Create a line plot
+        
+        Args:
+            x: X-axis data
+            y: Y-axis data
+            title: Plot title
+            xlabel: X-axis label
+            ylabel: Y-axis label
+            label: Data series label
+        
+        Returns:
+            ASCII art string representation of the plot
+        """
+        if not self.available:
+            return self._fallback_plot(x, y, title)
+        
+        try:
+            plt.clf()  # Clear previous plot
+            plt.plot_size(self.width, self.height)
+            plt.plot(x, y, label=label)
+            plt.title(title)
+            plt.xlabel(xlabel)
+            plt.ylabel(ylabel)
+            if label:
+                plt.legend()
+            
+            # Get the plot as string
+            return plt.build()
+        
+        except Exception as e:
+            logger.error(f"Plotting failed: {e}")
+            return self._fallback_plot(x, y, title)
+    
+    def plot_multiple_lines(
+        self,
+        data: List[Tuple[List[float], List[float], str]],
+        title: str = "Multi-Line Plot",
+        xlabel: str = "X",
+        ylabel: str = "Y"
+    ) -> str:
+        """
+        Create a multi-line plot
+        
+        Args:
+            data: List of (x, y, label) tuples
+            title: Plot title
+            xlabel: X-axis label
+            ylabel: Y-axis label
+        
+        Returns:
+            ASCII art string representation of the plot
+        """
+        if not self.available:
+            return f"[Plot unavailable: plotext not installed]\n{title}"
+        
+        try:
+            plt.clf()
+            plt.plot_size(self.width, self.height)
+            
+            for x, y, label in data:
+                plt.plot(x, y, label=label)
+            
+            plt.title(title)
+            plt.xlabel(xlabel)
+            plt.ylabel(ylabel)
+            plt.legend()
+            
+            return plt.build()
+        
+        except Exception as e:
+            logger.error(f"Multi-line plotting failed: {e}")
+            return f"[Plot error: {str(e)}]\n{title}"
+    
+    def plot_scatter(
+        self,
+        x: List[float],
+        y: List[float],
+        title: str = "Scatter Plot",
+        xlabel: str = "X",
+        ylabel: str = "Y",
+        label: Optional[str] = None
+    ) -> str:
+        """Create a scatter plot"""
+        if not self.available:
+            return self._fallback_plot(x, y, title)
+        
+        try:
+            plt.clf()
+            plt.plot_size(self.width, self.height)
+            plt.scatter(x, y, label=label)
+            plt.title(title)
+            plt.xlabel(xlabel)
+            plt.ylabel(ylabel)
+            if label:
+                plt.legend()
+            
+            return plt.build()
+        
+        except Exception as e:
+            logger.error(f"Scatter plot failed: {e}")
+            return self._fallback_plot(x, y, title)
+    
+    def plot_bar(
+        self,
+        categories: List[str],
+        values: List[float],
+        title: str = "Bar Chart",
+        xlabel: str = "Category",
+        ylabel: str = "Value"
+    ) -> str:
+        """Create a bar chart"""
+        if not self.available:
+            return f"[Plot unavailable: plotext not installed]\n{title}"
+        
+        try:
+            plt.clf()
+            plt.plot_size(self.width, self.height)
+            plt.bar(categories, values)
+            plt.title(title)
+            plt.xlabel(xlabel)
+            plt.ylabel(ylabel)
+            
+            return plt.build()
+        
+        except Exception as e:
+            logger.error(f"Bar chart failed: {e}")
+            return f"[Plot error: {str(e)}]\n{title}"
+    
+    def plot_histogram(
+        self,
+        data: List[float],
+        bins: int = 20,
+        title: str = "Histogram",
+        xlabel: str = "Value",
+        ylabel: str = "Frequency"
+    ) -> str:
+        """Create a histogram"""
+        if not self.available:
+            return f"[Plot unavailable: plotext not installed]\n{title}"
+        
+        try:
+            plt.clf()
+            plt.plot_size(self.width, self.height)
+            plt.hist(data, bins=bins)
+            plt.title(title)
+            plt.xlabel(xlabel)
+            plt.ylabel(ylabel)
+            
+            return plt.build()
+        
+        except Exception as e:
+            logger.error(f"Histogram failed: {e}")
+            return f"[Plot error: {str(e)}]\n{title}"
+    
+    def _fallback_plot(self, x: List[float], y: List[float], title: str) -> str:
+        """
+        Simple fallback visualization when plotext is unavailable
+        Creates a basic ASCII representation
+        """
+        if not x or not y:
+            return f"[No data to plot]\n{title}"
+        
+        # Simple text representation
+        output = [f"\n{title}", "─" * 40]
+        
+        # Show min, max, mean
+        try:
+            output.append(f"Data points: {len(y)}")
+            output.append(f"Min: {min(y):.2f}")
+            output.append(f"Max: {max(y):.2f}")
+            output.append(f"Mean: {sum(y)/len(y):.2f}")
+        except Exception:
+            output.append("Data statistics unavailable")
+        
+        output.append("─" * 40)
+        output.append("[Install plotext for visual charts: pip install plotext]")
+        
+        return "\n".join(output)
+    
+    @staticmethod
+    def is_available() -> bool:
+        """Check if plotting is available"""
+        return PLOTEXT_AVAILABLE
+
+
+# Convenience functions for quick plotting
+
+def plot_quick_line(x: List[float], y: List[float], title: str = "Plot") -> str:
+    """Quick line plot"""
+    plotter = ASCIIPlotter()
+    return plotter.plot_line(x, y, title=title)
+
+
+def plot_quick_bar(categories: List[str], values: List[float], title: str = "Chart") -> str:
+    """Quick bar chart"""
+    plotter = ASCIIPlotter()
+    return plotter.plot_bar(categories, values, title=title)
+
+
+# Example usage and testing
+def example_usage():
+    """Demonstrate ASCII plotting capabilities"""
+    
+    print("ASCII Plotter Demo\n")
+    print("=" * 70)
+    
+    # Check availability
+    if not ASCIIPlotter.is_available():
+        print("❌ plotext not installed")
+        print("Install with: pip install plotext")
+        return
+    
+    print("✅ plotext available\n")
+    
+    # Example 1: Simple line plot
+    x = list(range(2020, 2025))
+    y = [100, 120, 115, 140, 150]
+    
+    plotter = ASCIIPlotter(width=60, height=15)
+    
+    print("Example 1: GDP Growth Over Time")
+    print(plotter.plot_line(x, y, title="GDP Growth (2020-2024)", 
+                           xlabel="Year", ylabel="GDP ($B)"))
+    
+    # Example 2: Multiple lines
+    print("\n\nExample 2: Multi-Country Comparison")
+    data = [
+        (x, [100, 110, 105, 115, 120], "USA"),
+        (x, [90, 95, 92, 100, 105], "UK"),
+        (x, [80, 85, 88, 95, 100], "Japan")
+    ]
+    print(plotter.plot_multiple_lines(data, title="GDP Growth Comparison",
+                                     xlabel="Year", ylabel="GDP Index"))
+    
+    # Example 3: Bar chart
+    print("\n\nExample 3: Quarterly Revenue")
+    quarters = ["Q1", "Q2", "Q3", "Q4"]
+    revenue = [250, 280, 290, 310]
+    print(plotter.plot_bar(quarters, revenue, title="2024 Revenue by Quarter",
+                          xlabel="Quarter", ylabel="Revenue ($M)"))
+    
+    print("\n" + "=" * 70)
+    print("✅ ASCII plotting demo complete!")
+
+
+if __name__ == "__main__":
+    example_usage()