client_app_FastAPI.py

# client_app_FastAPI.py — CLI insights assistant using FASTAPI Client + RAG search
# - Friendly error handling (Auth/RateLimit/HTTP/Connection)
# - Optional LLM summarizer (Ollama/OpenAI) with citations
# - Flags: --server, --token, --verbose, --llm, --llm-provider, --ollama-url, --ollama-model, --openai-model

from __future__ import annotations

from dotenv import load_dotenv, find_dotenv
load_dotenv(find_dotenv())  # loads ${workspaceFolder}/.env by default

import argparse
import os
import sys
import textwrap
from typing import Any, Dict, Optional

from FastAPI_client import (
    FastAPIClient,
    AuthError,
    RateLimitError,
    FastAPIHTTPError,
    FastAPIConnectionError,
)

from summarizer import summarize  # provider-agnostic: Ollama or OpenAI


# -------- helpers --------

def fmt_hit(hit: Dict[str, Any]) -> str:
    src = hit.get("source", {}) or {}
    badge = []
    if src.get("doc_type"):
        badge.append(src["doc_type"])
    if src.get("page") is not None:
        badge.append(f"p.{src['page']}")
    if src.get("row") is not None:
        badge.append(f"row {src['row']}")
    where = " • ".join(badge) if badge else "source"
    content = (hit.get("content") or "").replace("\n", " ")
    preview = content[:200] + ("…" if len(content) > 200 else "")
    score = hit.get("score", 0.0)
    return f"- [{where}] {preview} (score={score:.3f})"


def print_error(e: Exception, verbose: bool = False) -> int:
    """Map exceptions to friendly guidance and return a non-zero exit code."""
    def vprint(msg: str) -> None:
        if verbose:
            print(msg)

    if isinstance(e, AuthError):
        print("❌ Authorization error.")
        print("→ Re-authenticate or request the missing scope/role.")
        print("   - Pass a token with --token or set FASTAPI_TOKEN.")
        print("   - Confirm you’re calling allowed tools/endpoints.")
        if getattr(e, "payload", None):
            vprint(f"[payload] {e.payload}")
        return 2

    if isinstance(e, RateLimitError):
        wait = getattr(e, "retry_after", None) or "a few"
        print("⏳ Rate limit hit (429).")
        print(f"→ Wait {wait} seconds and try again.")
        print("   - Reduce result size (e.g., lower k/per_page), or slow requests.")
        if getattr(e, "payload", None):
            vprint(f"[payload] {e.payload}")
        return 3

    if isinstance(e, FastAPIConnectionError):
        print("🔌 Cannot reach the server.")
        print("→ Is the server running? Try:")
        print("   uvicorn FastAPI_server:app --port 8799 --reload")
        print("   - Check --server URL, firewall/VPN, and network connectivity.")
        vprint(str(e))
        return 4

    if isinstance(e, FastAPIHTTPError):
        status = e.status
        print(f"❌ HTTP error ({status}).")
        if status == 400:
            print("→ Bad request. Check parameters (paths, text_col, k).")
        elif status == 404:
            print("→ Not found. For ingest: verify file path. For search: try a broader query.")
        elif status == 413:
            print("→ Payload too large. Split the file or reduce fields/text.")
        elif status == 422:
            print("→ Validation error. Ensure required fields exist and are correctly typed.")
        elif 500 <= status < 600:
            print("→ Server issue. Try again shortly or check server logs.")
        else:
            print("→ Fix parameters and retry, or inspect server logs.")
        if getattr(e, "payload", None):
            vprint(f"[payload] {e.payload}")
        return 5

    # Fallback
    print("❌ Unexpected error.")
    if verbose:
        import traceback
        traceback.print_exc()
    else:
        print(str(e))
    return 1


def make_host(args) -> FastAPIClient:
    base_url = args.server or os.getenv("FASTAPI_SERVER_URL", "http://127.0.0.1:8799")
    token = args.token or os.getenv("FASTAPI_TOKEN")
    return FastAPIClient(base_url=base_url, token=token, max_attempts=3)


# -------- commands --------

def cmd_ingest_pdf(args) -> int:
    host = make_host(args)
    try:
        res = host.ingest_pdf(args.path, doc_type=args.doc_type)
        print(res)
        return 0
    except Exception as e:
        return print_error(e, verbose=args.verbose)


def cmd_ingest_csv(args) -> int:
    host = make_host(args)
    try:
        res = host.ingest_csv(args.path, text_col=args.text_col, doc_type=args.doc_type)
        print(res)
        return 0
    except Exception as e:
        return print_error(e, verbose=args.verbose)


def cmd_ask(args) -> int:
    host = make_host(args)
    try:
        res = host.search_docs(args.query, k=args.k)
        hits = res.get("hits", []) if isinstance(res, dict) else []
        if not hits:
            print("ℹ️  No matches. Try widening the query or ingesting more documents.")
            return 0

        print("Top matches:")
        for h in hits:
            print(fmt_hit(h))

        # Build snippets + citations for summarizer
        snippets = [h.get("content", "") for h in hits]
        citations = [str(h.get("source", {}) or {}) for h in hits]

        llm_answer = None
        if args.llm:
            llm_answer = summarize(
                args.query,
                snippets,
                citations,
                provider=args.llm_provider,
                ollama_url=args.ollama_url,
                ollama_model=args.ollama_model,
                openai_model=args.openai_model,
            )

        if llm_answer:
            print("\nAnswer (LLM, cited):\n", llm_answer)
        else:
            # Fallback: extractive answer from top snippets
            joined = " ".join(snippets)[:1500]
            answer = textwrap.shorten(joined, width=500, placeholder=" …")
            print("\nAnswer (extractive):\n", answer)

        print("\nCitations:")
        for h in hits:
            print(" -", h.get("source", {}))
        return 0

    except Exception as e:
        return print_error(e, verbose=args.verbose)


# -------- CLI --------

def main() -> None:
    p = argparse.ArgumentParser(description="Insights Assistant CLI — RAG + FASTAPI (friendly errors + optional LLM)")
    p.add_argument("--server", help="FastAPI Server URL (default: env FASTAPI_SERVER_URL or http://127.0.0.1:8799)")
    p.add_argument("--token", help="Bearer token for auth (optional, or set FASTAPI_TOKEN)")
    p.add_argument("--verbose", action="store_true", help="Show detailed payloads/tracebacks on error")

    sub = p.add_subparsers(dest="cmd")

    p1 = sub.add_parser("ingest-pdf", help="Ingest a PDF")
    p1.add_argument("path")
    p1.add_argument("--doc-type", default="pdf")
    p1.set_defaults(func=cmd_ingest_pdf)

    p2 = sub.add_parser("ingest-csv", help="Ingest a CSV")
    p2.add_argument("path")
    p2.add_argument("--text-col", default=None, help="Optional column that contains text")
    p2.add_argument("--doc-type", default="csv")
    p2.set_defaults(func=cmd_ingest_csv)

    p3 = sub.add_parser("ask", help="Ask a question against the RAG index")
    p3.add_argument("query")
    p3.add_argument("-k", type=int, default=5)
    # LLM options
    p3.add_argument("--llm", action="store_true", help="Use LLM to write a concise, cited summary")
    p3.add_argument("--llm-provider", default=os.getenv("SUMMARIZER_PROVIDER", "ollama"),
                    choices=["ollama", "openai"], help="LLM backend (default: ollama)")
    p3.add_argument("--ollama-url", default=os.getenv("OLLAMA_URL", "http://127.0.0.1:11434"))
    p3.add_argument("--ollama-model", default=os.getenv("OLLAMA_MODEL", "llama3.1:8b"))
    p3.add_argument("--openai-model", default=os.getenv("OPENAI_MODEL", "gpt-4o-mini"))
    p3.set_defaults(func=cmd_ask)

    args = p.parse_args()
    if not getattr(args, "cmd", None):
        p.print_help()
        sys.exit(0)

    rc = args.func(args)
    sys.exit(rc)


if __name__ == "__main__":
    main()