ifs-rag-assistant-cli 2.2.2__py3-none-any.whl

ifs_rag_assistant_cli/__init__.py

@@ -0,0 +1,5 @@
+"""
+IFS RAG Assistant CLI - Command-line interface for IFS RAG Assistant Q&A system.
+"""
+
+__version__ = "2.2.2"

ifs_rag_assistant_cli/auth_client.py

@@ -0,0 +1,182 @@
+"""
+Unified authentication and backend client wrapper.
+
+Handles the complete flow of device code authentication,
+session creation, and backend API access.
+"""
+
+from ipaddress import ip_address
+from typing import Optional
+from urllib.parse import urlparse
+
+from ifs_rag_assistant_cli.backend_client import BackendClient
+from ifs_rag_assistant_cli.config import Config, load_config
+from ifs_rag_assistant_cli.oauth import create_device_authenticator
+from ifs_rag_assistant_cli.session import SessionManager
+
+
+class AuthenticatedClient:
+    """
+    Unified client for authenticated backend API access.
+
+    Manages the complete authentication flow:
+    1. Load cached session if available
+    2. If not, perform Device Code OAuth authentication
+    3. Create backend session with OAuth token
+    4. Cache session for future use
+    """
+
+    def __init__(
+        self,
+        backend_url: Optional[str] = None,
+        keycloak_url: Optional[str] = None,
+        realm: Optional[str] = None,
+        client_id: Optional[str] = None,
+        config: Optional[Config] = None
+    ):
+        """
+        Initialize authenticated client.
+
+        Args:
+            backend_url: Backend API URL (overrides config)
+            keycloak_url: Keycloak server URL (overrides config)
+            realm: Keycloak realm (overrides config)
+            client_id: OAuth client ID (overrides config)
+            config: Config instance. If None, loads from file/env
+        """
+        # Load config if not provided
+        if config is None:
+            config = load_config()
+
+        self.config = config
+
+        # Initialize session manager
+        cache_dir = getattr(config, 'cache_dir', '~/.ifs-rag-assistant-cli')
+        self.session_mgr = SessionManager(cache_dir)
+
+        # Initialize backend client
+        api_root = backend_url or getattr(config, 'api_root', 'http://localhost:8000')
+        timeout = getattr(config, 'timeout', 300)
+        self.backend = BackendClient(str(api_root), int(timeout))
+
+        # Initialize OAuth authenticator using factory
+        keycloak_url = keycloak_url or getattr(
+            config, 'keycloak_server_url', 'http://localhost:8080'
+        )
+        realm = realm or getattr(config, 'keycloak_realm', 'master')
+        client_id = client_id or getattr(config, 'keycloak_client_id', 'ifs-rag')
+
+        # Get OAuth mode and custom wrapper URL from config
+        oauth_mode = getattr(config, 'oauth_device_flow_mode', 'standard')
+        custom_wrapper_url = getattr(config, 'oauth_custom_wrapper_url', None)
+
+        self.oauth = create_device_authenticator(
+            mode=oauth_mode,
+            client_id=str(client_id),
+            keycloak_server_url=keycloak_url,
+            realm=realm,
+            custom_wrapper_url=custom_wrapper_url
+        )
+
+    @staticmethod
+    def _is_local_api_root(api_root: str) -> bool:
+        """Return True when API root points to a local development host."""
+        parsed = urlparse(str(api_root))
+        host = (parsed.hostname or "").strip().lower()
+
+        if not host:
+            return False
+
+        if host == "localhost":
+            return True
+
+        try:
+            addr = ip_address(host)
+            return addr.is_loopback
+        except ValueError:
+            return False
+
+    def _is_auth_disabled(self) -> bool:
+        """Return True when auth_mode is explicitly disabled."""
+        auth_mode = str(getattr(self.config, "auth_mode", "oauth")).strip().lower()
+        if auth_mode not in ("oauth", "disabled"):
+            raise RuntimeError(
+                f"Invalid auth_mode '{auth_mode}'. Supported values: 'oauth', 'disabled'."
+            )
+        return auth_mode == "disabled"
+
+    def ensure_authenticated(self) -> None:
+        """
+        Ensure user is authenticated.
+
+        Attempts to load cached session if available.
+        If not, performs Device Code OAuth flow and creates new session.
+
+        Raises:
+            RuntimeError: If authentication fails
+        """
+        if self._is_auth_disabled():
+            if not self._is_local_api_root(self.backend.backend_url):
+                raise RuntimeError(
+                    "Authentication is disabled, but api_root is not local. "
+                    "Set auth_mode='oauth' or use a localhost/loopback api_root for development."
+                )
+
+            print("ℹ️  Authentication disabled for local development (auth_mode=disabled)")
+            print("ℹ️  Proceeding without OAuth and backend login session")
+            return
+
+        # Try to load cached session
+        session_id = self.session_mgr.load_session()
+
+        if session_id:
+            print("✅ Using cached session")
+            # Set the session in the backend client
+            self.backend.set_session(session_id)
+            return
+
+        print("🔐 Authentication required")
+
+        # Perform Device Code OAuth flow
+        token, _token_type = self.oauth.authenticate()
+
+        # Exchange OAuth token for backend session
+        print("🔄 Creating backend session...")
+        try:
+            if self.oauth.uses_refresh_session_login():
+                session_id = self.backend.login_with_refresh_token(token)
+            else:
+                session_id = self.backend.login_with_token(token)
+            self.session_mgr.save_session(session_id)
+            print("✅ Authenticated successfully!")
+        except RuntimeError as e:
+            raise RuntimeError(f"Failed to create session: {e}") from e
+
+    def logout(self) -> None:
+        """
+        Logout and clear cached session.
+
+        Raises:
+            RuntimeError: If logout fails
+        """
+        if self._is_auth_disabled():
+            self.session_mgr.clear_all()
+            print("ℹ️  Authentication is disabled (auth_mode=disabled): no backend logout required")
+            print("✅ Local session cache cleared")
+            return
+
+        self.backend.logout()
+        self.session_mgr.clear_all()
+        print("✅ Logged out successfully")
+
+    def close(self) -> None:
+        """Close backend connection."""
+        self.backend.close()
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit."""
+        self.close()

ifs_rag_assistant_cli/backend_client.py

@@ -0,0 +1,298 @@
+"""
+Backend API client for IFS RAG Assistant service.
+
+Handles communication with the FastAPI backend,
+including authentication and request/response handling.
+"""
+
+from typing import Any, Optional, cast
+
+import requests
+from requests.exceptions import RequestException
+
+SESSION_EXPIRED_MESSAGE = (
+    "Authentication failed: your session may have expired or is no longer valid. "
+    "Please run 'ifs-rag-assistant-cli logout' and try again. "
+    "If the problem persists, contact your service administrator."
+)
+
+
+class SessionExpiredError(RuntimeError):
+    """Raised when backend returns 401 due to expired or invalid session."""
+
+
+class BackendClient:
+    """
+    Client for communicating with IFS RAG backend API.
+
+    Handles authentication via OAuth tokens and session cookies,
+    and provides methods for RAG operations (ask, search, etc.).
+    """
+
+    def __init__(self, backend_url: str, timeout: int = 300):
+        """
+        Initialize backend client.
+
+        Args:
+            backend_url: Base URL of backend API
+            timeout: Request timeout in seconds
+        """
+        self.backend_url = backend_url.rstrip('/')
+        self.timeout = timeout
+        self.session = requests.Session()
+
+    def set_session(self, session_id: str) -> None:
+        """
+        Set session ID in client cookies.
+
+        Args:
+            session_id: Session ID to use for authentication
+        """
+        self.session.cookies.set('session_id', session_id)
+
+    def _raise_request_error(self, operation: str, error: RequestException) -> None:
+        """Raise a user-friendly error message for request failures."""
+        response = getattr(error, "response", None)
+        if response is not None and response.status_code == 401:
+            raise SessionExpiredError(SESSION_EXPIRED_MESSAGE) from error
+        raise RuntimeError(f"{operation} failed: {error}") from error
+
+    def login_with_token(self, access_token: str) -> str:
+        """
+        Authenticate with OAuth access token and create session.
+
+        Args:
+            access_token: OAuth access token from Keycloak
+
+        Returns:
+            Session ID (extracted from response cookies)
+
+        Raises:
+            RuntimeError: If login fails
+        """
+        try:
+            resp = self.session.post(
+                f"{self.backend_url}/login",
+                json={"access_token": access_token},
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            raise RuntimeError(f"Login failed: {e}") from e
+
+        # Session ID is returned in Set-Cookie header
+        if 'session_id' not in self.session.cookies:
+            raise RuntimeError("No session_id in login response")
+
+        return str(self.session.cookies.get('session_id'))
+
+    def login_with_refresh_token(self, refresh_token: str) -> str:
+        """
+        Authenticate with OAuth refresh token (offline token) and create session.
+
+        Args:
+            refresh_token: OAuth refresh token (offline token) from authentication
+
+        Returns:
+            Session ID (extracted from response cookies)
+
+        Raises:
+            RuntimeError: If login fails
+        """
+        try:
+            resp = self.session.post(
+                f"{self.backend_url}/login/refresh",
+                json={"refresh_token": refresh_token},
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            raise RuntimeError(f"Login with refresh token failed: {e}") from e
+
+        # Session ID is returned in Set-Cookie header
+        if 'session_id' not in self.session.cookies:
+            raise RuntimeError("No session_id in login response")
+
+        return str(self.session.cookies.get('session_id'))
+
+    def ask(self, query: str, conversation_id: Optional[str] = None, client_id: Optional[str] = None) -> dict[str, Any]:
+        """
+        Ask a question to the RAG system.
+
+        Args:
+            query: The question to ask
+            conversation_id: Optional conversation identifier to continue a thread
+            client_id: Optional client identifier for tracking
+
+        Returns:
+            Response dictionary with answer, citations, conversation_id, turn_id, question_id, answer_id, created_at
+
+        Raises:
+            RuntimeError: If request fails
+        """
+        payload = {"query": query}
+        if conversation_id:
+            payload["conversation_id"] = conversation_id
+        if client_id:
+            payload["client_id"] = client_id
+
+        try:
+            resp = self.session.post(
+                f"{self.backend_url}/ask",
+                json=payload,
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Ask request", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def search(self, query: str) -> dict[str, Any]:
+        """
+        Search the RAG index.
+
+        Args:
+            query: Search query
+
+        Returns:
+            Response dictionary with search results (context, citations)
+
+        Raises:
+            RuntimeError: If request fails
+        """
+        try:
+            resp = self.session.get(
+                f"{self.backend_url}/search",
+                params={"query": query},
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Search request", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def logout(self) -> None:
+        """
+        Logout from backend (invalidate session).
+
+        Raises:
+            RuntimeError: If logout request fails
+        """
+        try:
+            self.session.post(
+                f"{self.backend_url}/logout",
+                timeout=self.timeout
+            )
+        except RequestException as e:
+            raise RuntimeError(f"Logout failed: {e}") from e
+
+    def health(self) -> dict[str, Any]:
+        """
+        Check backend health status.
+
+        Returns:
+            Response dictionary with health information
+
+        Raises:
+            RuntimeError: If health check fails
+        """
+        try:
+            resp = self.session.get(
+                f"{self.backend_url}/health",
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Health check", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def submit_feedback(self, conversation_id: str, answer_id: str,
+                       vote: Optional[str] = None, reason: Optional[str] = None,
+                       client_id: Optional[str] = None) -> dict[str, Any]:
+        """
+        Submit thumbs up/down feedback for a previously returned answer.
+
+        Args:
+            conversation_id: Conversation identifier
+            answer_id: Answer identifier to provide feedback for
+            vote: 'up', 'down', or None to clear vote
+            reason: Optional feedback reason text
+            client_id: Optional client identifier for tracking
+
+        Returns:
+            Response dictionary with feedback status
+
+        Raises:
+            RuntimeError: If request fails
+        """
+        payload = {
+            "conversation_id": conversation_id,
+            "answer_id": answer_id,
+        }
+        if vote:
+            payload["vote"] = vote
+        if reason:
+            payload["reason"] = reason
+        if client_id:
+            payload["client_id"] = client_id
+
+        try:
+            resp = self.session.post(
+                f"{self.backend_url}/feedback",
+                json=payload,
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Submit feedback request", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def get_models(self) -> dict[str, Any]:
+        """
+        Get list of available models from the backend.
+
+        Returns:
+            Response dictionary with list of models
+
+        Raises:
+            RuntimeError: If request fails
+        """
+        try:
+            resp = self.session.get(
+                f"{self.backend_url}/models",
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Get models request", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def get_usage_guide(self) -> dict[str, Any]:
+        """
+        Get usage guide from the backend.
+
+        Returns:
+            Response dictionary with usage guide content
+
+        Raises:
+            RuntimeError: If request fails
+        """
+        try:
+            resp = self.session.get(
+                f"{self.backend_url}/usage",
+                timeout=self.timeout
+            )
+            resp.raise_for_status()
+        except RequestException as e:
+            self._raise_request_error("Get usage guide request", e)
+
+        return cast(dict[str, Any], resp.json())
+
+    def close(self) -> None:
+        """Close the HTTP session."""
+        self.session.close()