Upload 14 files

src/README.md

@@ -0,0 +1,75 @@
+# Handbook Generator (AI Engineering Assignment)
+
+Same technology as the **policy** project: **Google ADK**, **LiteLLM** (OpenAI), and **Streamlit**. The UI talks to the ADK agent **directly** (no API). The agent uses a **RAG tool** (ChromaDB) to answer from uploaded PDFs.
+
+## Features
+
+- **PDF upload** — Upload PDFs; text is extracted, chunked, embedded (OpenAI), stored in **ChromaDB** (local).
+- **Chat** — ADK agent runs in the same process; agent calls **RAG tool** `query_uploaded_documents` and answers with the LLM (OpenAI via LiteLLM).
+- **Handbook generation** — Request a 20,000+ word handbook; generation uses RAG and runs section-by-section.
+- **Export** — Download the handbook as Markdown.
+
+## Architecture
+
+- **Streamlit** (`streamlit_app.py`) → UI; imports **runner_app** to run the agent directly.
+- **runner_app.py** → ADK Runner + session; `run_chat(message)` runs the agent (sync wrapper around `runner.run_async`).
+- **agent.py** → ADK Agent (LiteLLM/OpenAI), tools = `[query_uploaded_documents]`.
+- **RAG** (`rag.py` + `rag_tools.py`) → ChromaDB + OpenAI embeddings.
+
+## Setup
+
+### 1. Python
+
+Use Python 3.10+.
+
+### 2. Install dependencies
+
+```bash
+cd ass2
+pip install -r requirements.txt
+```
+
+### 3. Environment
+
+Create a `.env` file in `ass2` (see `.env.example`):
+
+```
+OPENAI_API_KEY=sk-your-openai-api-key-here
+MODEL=gpt-4o
+```
+
+## Run (single command)
+
+```bash
+cd ass2
+streamlit run streamlit_app.py
+```
+
+Open **http://localhost:8501**. No separate API server.
+
+## How to use
+
+1. **Upload PDFs** — In "Upload PDFs", select PDFs and click **Index PDFs**.
+2. **Chat** — In "Chat", ask questions; the ADK agent uses the RAG tool and answers from your documents.
+3. **Generate handbook** — In "Generate Handbook", enter a topic and click **Generate handbook**, then download as Markdown.
+
+## Project structure (all in `ass2`)
+
+| File | Purpose |
+|------|--------|
+| `streamlit_app.py` | Streamlit UI (upload, chat, handbook) |
+| `runner_app.py` | ADK Runner + session; `run_chat(message)` for Streamlit |
+| `agent.py` | ADK agent (LiteLLM/OpenAI) + RAG tool |
+| `prompt.py` | Agent name, description, instruction |
+| `rag_tools.py` | ADK tool: `query_uploaded_documents` |
+| `callback.py` | ADK callbacks |
+| `rag.py` | ChromaDB + OpenAI embeddings |
+| `pdf_processor.py` | PDF text extraction and chunking |
+| `handbook_generator.py` | 20k-word handbook generation |
+| `config.py` | Settings and paths |
+
+## Tech stack
+
+- **Agent:** Google ADK, LiteLLM (OpenAI)
+- **RAG:** OpenAI embeddings, ChromaDB (local)
+- **UI:** Streamlit (agent runs in-process, no FastAPI)

src/agent.py

@@ -0,0 +1,42 @@
+"""
+ADK agent for the Handbook Generator.
+Uses Google ADK + LiteLLM (OpenAI) + RAG tools.
+"""
+import os
+from dotenv import load_dotenv
+from google.adk.agents.llm_agent import Agent
+from google.adk.models.lite_llm import LiteLlm
+
+import prompt as prmpt
+import callback as cb
+import rag_tools as tls
+
+# 🔑 Load .env file
+load_dotenv()
+
+openai_api_key = os.getenv("OPENAI_API_KEY")
+model = os.getenv("MODEL", "openai/gpt-4o")
+
+if not openai_api_key:
+    raise ValueError("OPENAI_API_KEY is not set in .env")
+
+os.environ["OPENAI_API_KEY"] = openai_api_key
+
+# Create the agent (same pattern as Policy)
+root_agent = Agent(
+    model=LiteLlm(
+        model=model,
+    ),
+    name=prmpt.AGENT_CONFIG["name"],
+    description=prmpt.AGENT_CONFIG["description"],
+    instruction=prmpt.AGENT_CONFIG["instruction"],
+    tools=[tls.query_uploaded_documents],
+    before_agent_callback=cb.before_agent_callback,
+    after_agent_callback=cb.after_agent_callback,
+    before_model_callback=cb.before_model_callback,
+    after_model_callback=cb.after_model_callback,
+    before_tool_callback=cb.before_tool_callback,
+    after_tool_callback=cb.after_tool_callback,
+    on_model_error_callback=cb.on_model_error_callback,
+    on_tool_error_callback=cb.on_tool_error_callback,
+)

src/app.py

@@ -0,0 +1,169 @@
+"""
+Handbook Generator — Gradio UI (legacy fallback).
+Primary UI is streamlit_app.py.
+Run: python app.py
+"""
+import asyncio
+import shutil
+from pathlib import Path
+
+import gradio as gr
+
+from config import GROK_API_KEY, UPLOADS_DIR, BASE_DIR
+from handbook_generator import build_handbook
+from rag import get_context_for_query, index_pdf, reset_index
+
+HANDBOOK_EXPORT_PATH = BASE_DIR / "handbook_export.md"
+
+
+def _run_async(coro):
+    """Run an async coroutine from sync Gradio code."""
+    try:
+        return asyncio.run(coro)
+    except RuntimeError:
+        import concurrent.futures
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            return pool.submit(asyncio.run, coro).result(timeout=300)
+
+
+def ensure_api_key():
+    if not GROK_API_KEY:
+        raise gr.Error(
+            "GROK_API_KEY is not set. Create a .env file in the ass2 folder with: GROK_API_KEY=your-key"
+        )
+
+
+def _file_path(f):
+    """Get path from Gradio file input (path string or object with .name)."""
+    if f is None:
+        return None
+    if isinstance(f, (str, Path)):
+        return Path(f)
+    return Path(getattr(f, "name", str(f)))
+
+
+def upload_and_index(files):
+    """Handle PDF upload(s) and index into LightRAG."""
+    if not files:
+        return "No files selected."
+    ensure_api_key()
+    reset_index()
+    saved = []
+    for f in (files if isinstance(files, list) else [files]):
+        path = _file_path(f)
+        if path is None or not path.exists():
+            continue
+        dest = UPLOADS_DIR / path.name
+        try:
+            shutil.copy(str(path), str(dest))
+        except Exception:
+            dest = path
+        try:
+            n = _run_async(index_pdf(dest, source_name=path.name))
+            saved.append(f"{path.name}: indexed")
+        except Exception as e:
+            saved.append(f"{path.name}: Error - {e}")
+    return "\n".join(saved) if saved else "No PDFs processed."
+
+
+def chat(message, history):
+    """RAG chat: retrieve context and answer using Grok via LiteLLM."""
+    ensure_api_key()
+    from litellm import completion
+    from config import CHAT_MODEL
+
+    context = _run_async(get_context_for_query(message))
+    if not context or not context.strip():
+        context = "No documents have been uploaded yet. Ask the user to upload PDFs first."
+
+    system = (
+        "You are a helpful assistant. Answer based ONLY on the following context "
+        "from the user's uploaded documents. If the answer is not in the context, say so clearly."
+    )
+    user_content = f"Context from uploaded documents:\n\n{context}\n\n---\n\nUser question: {message}"
+
+    resp = completion(
+        model=CHAT_MODEL,
+        messages=[
+            {"role": "system", "content": system},
+            {"role": "user", "content": user_content},
+        ],
+        api_key=GROK_API_KEY,
+        max_tokens=1500,
+        temperature=0.3,
+    )
+    return (resp.choices[0].message.content or "").strip()
+
+
+def run_handbook_simple(topic):
+    """Generate handbook and return (status, markdown)."""
+    ensure_api_key()
+    if not (topic and topic.strip()):
+        return "Enter a topic first.", ""
+    status_msgs = []
+    try:
+        full_md = _run_async(build_handbook(topic.strip(), on_progress=status_msgs.append))
+        status = "\n".join(status_msgs) if status_msgs else "Done."
+        return status, full_md
+    except Exception as e:
+        return f"Error: {e}", ""
+
+
+with gr.Blocks(title="Handbook Generator", theme=gr.themes.Soft()) as demo:
+    gr.Markdown("# Handbook Generator\nUpload PDFs, chat about them, and generate a 20,000+ word handbook.")
+
+    with gr.Tab("Upload PDFs"):
+        file_input = gr.File(
+            file_count="multiple",
+            file_types=[".pdf"],
+            label="Upload one or more PDFs",
+        )
+        index_btn = gr.Button("Index PDFs")
+        index_out = gr.Textbox(label="Index result", lines=4)
+
+    with gr.Tab("Chat"):
+        chatbot = gr.ChatInterface(
+            fn=chat,
+            type="messages",
+            title="Ask questions about your uploaded documents",
+        )
+
+    with gr.Tab("Generate Handbook"):
+        gr.Markdown(
+            "Enter a topic (e.g. *Create a handbook on Retrieval-Augmented Generation*). "
+            "Generation may take several minutes."
+        )
+        topic_in = gr.Textbox(
+            label="Handbook topic",
+            placeholder="e.g. Retrieval-Augmented Generation",
+            lines=1,
+        )
+        gen_btn = gr.Button("Generate 20k-word handbook")
+        status_out = gr.Textbox(label="Status", lines=4, interactive=False)
+        handbook_out = gr.Markdown(label="Handbook (Markdown)")
+        export_btn = gr.DownloadButton("Export as Markdown", visible=False)
+
+    index_btn.click(
+        fn=lambda files: upload_and_index(files) if files else "No files selected.",
+        inputs=[file_input],
+        outputs=[index_out],
+    )
+
+    def do_handbook(topic):
+        status, md = run_handbook_simple(topic)
+        if md:
+            HANDBOOK_EXPORT_PATH.write_text(md, encoding="utf-8")
+        return (
+            status,
+            md,
+            gr.update(visible=bool(md), value=str(HANDBOOK_EXPORT_PATH) if md else None),
+        )
+
+    gen_btn.click(
+        fn=do_handbook,
+        inputs=[topic_in],
+        outputs=[status_out, handbook_out, export_btn],
+    )
+
+if __name__ == "__main__":
+    demo.launch(server_name="127.0.0.1", server_port=7860)

src/callback.py

@@ -0,0 +1,241 @@
+"""
+ADK callbacks for logging and optional audit (same as policy/callback.py).
+"""
+
+import logging
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+_audit_sink: Optional[Any] = None
+
+
+def set_audit_sink(sink: Any) -> None:
+    global _audit_sink
+    _audit_sink = sink
+
+
+def _get_session_id(context: Any) -> Optional[str]:
+    try:
+        if hasattr(context, "session") and context.session is not None:
+            return getattr(context.session, "id", None) or getattr(
+                context.session, "session_id", None
+            )
+    except Exception:
+        pass
+    return None
+
+
+def _get_message_preview(content: Any, max_len: int = 500) -> Optional[str]:
+    if content is None:
+        return None
+    try:
+        if hasattr(content, "parts") and content.parts:
+            text = getattr(content.parts[0], "text", None) or str(content.parts[0])[:max_len]
+            return (text or "")[:max_len] if text else None
+        if isinstance(content, str):
+            return content[:max_len]
+        return str(content)[:max_len]
+    except Exception:
+        return None
+
+
+def _emit(event: dict) -> None:
+    logger.debug("[ADK callback] %s", event.get("event_type"), extra=event)
+    if _audit_sink is not None and hasattr(_audit_sink, "store"):
+        try:
+            _audit_sink.store(event)
+        except Exception as e:
+            logger.warning("[ADK callback] audit sink store failed: %s", e)
+
+
+def _context_from_args(*args: Any, **kwargs: Any) -> Any:
+    return kwargs.get("callback_context") or (args[0] if args else None)
+
+
+def before_agent_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "before_agent",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": None,
+            "message_preview": _get_message_preview(getattr(context, "user_content", None)),
+            "has_error": False,
+            "details": {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] before_agent failed: %s", e)
+    return None
+
+
+def after_agent_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "after_agent",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": None,
+            "message_preview": _get_message_preview(getattr(context, "user_content", None)),
+            "has_error": False,
+            "details": {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] after_agent failed: %s", e)
+    return None
+
+
+def before_model_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    llm_request = kwargs.get("llm_request")
+    if context is None:
+        return None
+    try:
+        message_preview = None
+        if llm_request is not None and hasattr(llm_request, "contents") and llm_request.contents:
+            last = llm_request.contents[-1]
+            message_preview = _get_message_preview(last)
+        event = {
+            "event_type": "before_model",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": None,
+            "message_preview": message_preview,
+            "has_error": False,
+            "details": {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] before_model failed: %s", e)
+    return None
+
+
+def after_model_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "after_model",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": None,
+            "message_preview": _get_message_preview(getattr(context, "user_content", None)),
+            "has_error": False,
+            "details": {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] after_model failed: %s", e)
+    return None
+
+
+def before_tool_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    tool_name = kwargs.get("tool_name")
+    tool_args = kwargs.get("tool_input") or kwargs.get("tool_args")
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "before_tool",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": tool_name,
+            "message_preview": str(tool_args)[:500] if tool_args is not None else None,
+            "has_error": False,
+            "details": {"tool_args": tool_args} if tool_args is not None else {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] before_tool failed: %s", e)
+    return None
+
+
+def after_tool_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    tool_name = kwargs.get("tool_name")
+    tool_result = kwargs.get("tool_result") or kwargs.get("result")
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "after_tool",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": tool_name,
+            "message_preview": str(tool_result)[:500] if tool_result is not None else None,
+            "has_error": False,
+            "details": {"tool_result": tool_result} if tool_result is not None else {},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] after_tool failed: %s", e)
+    return None
+
+
+def on_model_error_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    error = kwargs.get("error")
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "on_model_error",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": None,
+            "message_preview": str(error)[:500] if error is not None else None,
+            "has_error": True,
+            "details": {"error": str(error)},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] on_model_error failed: %s", e)
+    return None
+
+
+def on_tool_error_callback(*args: Any, **kwargs: Any) -> Optional[Any]:
+    context = _context_from_args(*args, **kwargs)
+    tool_name = kwargs.get("tool_name")
+    error = kwargs.get("error")
+    if context is None:
+        return None
+    try:
+        event = {
+            "event_type": "on_tool_error",
+            "agent_name": getattr(context, "agent_name", None),
+            "invocation_id": getattr(context, "invocation_id", None),
+            "user_id": getattr(context, "user_id", None),
+            "session_id": _get_session_id(context),
+            "tool_name": tool_name,
+            "message_preview": str(error)[:500] if error is not None else None,
+            "has_error": True,
+            "details": {"error": str(error)},
+        }
+        _emit(event)
+    except Exception as e:
+        logger.warning("[ADK callback] on_tool_error failed: %s", e)
+    return None

src/config.py

@@ -0,0 +1,34 @@
+"""Configuration for the Handbook Generator app."""
+import os
+from pathlib import Path
+
+# Load from .env if present
+from dotenv import load_dotenv
+load_dotenv()
+
+# ── API Keys ──────────────────────────────────────────────────────────
+OPENAI_API_KEY = os.getenv("OPENAI_API_KEY", "")
+CHAT_MODEL = os.getenv("MODEL", "openai/gpt-4o").strip() or "openai/gpt-4o"
+EMBEDDING_MODEL = "text-embedding-3-small"
+
+# Supabase
+SUPABASE_URL = os.getenv("SUPABASE_URL", "")
+SUPABASE_KEY = os.getenv("SUPABASE_KEY", "")
+
+# ── Paths ─────────────────────────────────────────────────────────────
+BASE_DIR = Path(__file__).resolve().parent
+UPLOADS_DIR = BASE_DIR / "uploads"
+UPLOADS_DIR.mkdir(exist_ok=True)
+
+# LightRAG working directory
+WORKING_DIR = BASE_DIR / "lightrag_working"
+WORKING_DIR.mkdir(exist_ok=True)
+
+# ── Chunking (used by pdf_processor) ─────────────────────────────────
+CHUNK_SIZE = 1000
+CHUNK_OVERLAP = 200
+
+# ── Handbook generation ───────────────────────────────────────────────
+TARGET_WORD_COUNT = 20000
+SECTION_WORD_TARGET = 1200
+MAX_SECTIONS = 25

src/extract_pdf.py

@@ -0,0 +1,12 @@
+"""Extract assignment PDF text to a file for reading."""
+from pypdf import PdfReader
+
+reader = PdfReader("AI-Engineering-Assignment.pdf")
+with open("assignment_text.txt", "w", encoding="utf-8") as f:
+    for i, page in enumerate(reader.pages):
+        text = page.extract_text()
+        if text:
+            f.write(f"--- Page {i+1} ---\n")
+            f.write(text)
+            f.write("\n\n")
+print("Done. Written to assignment_text.txt")

src/handbook_export.md

@@ -0,0 +1,30 @@
+# jungle book
+
+## Introduction
+
+"The Jungle Book," a timeless classic penned by Rudyard Kipling, is an exemplary piece of literature that continues to captivate readers of all ages. Originally published in 1894, this collection of stories has been celebrated for its vibrant depiction of the natural world and its profound exploration of human nature through the lens of animal allegories. The tales unfold in the lush, mysterious jungles of India, where anthropomorphized animals and human characters coexist, revealing insights into society, morality, and the intrinsic link between man and nature.
+
+### Overview
+
+At its core, "The Jungle Book" is a compilation of stories and poems, with the most renowned being the tales of Mowgli, a young boy raised by wolves in the Indian jungle. These narratives are not merely stories of adventure and wildlife; they are rich tapestries woven with themes of identity, belonging, and the struggle between civilization and the wild. Kipling's masterful storytelling is complemented by his intricate descriptions of the jungle environment, which becomes a character in its own right, embodying both beauty and peril.
+
+The structure of "The Jungle Book" is unique, as it oscillates between the adventures of Mowgli and other standalone tales featuring a diverse array of characters, such as Rikki-Tikki-Tavi, the valiant mongoose, and Kotick, the white seal. This collection is a mosaic of narratives that, while distinct, collectively paint a vivid picture of Kipling's imagined world. Each story serves as a parable, imparting lessons about courage, loyalty, and the consequences of human actions on the natural world.
+
+### Importance
+
+"The Jungle Book" holds a significant place in both literary and cultural history. Its importance is multifaceted, spanning from its contributions to children's literature to its impact on popular culture. The book is celebrated for its ability to transcend the boundaries of age and time, offering insights that resonate with both young readers and adults.
+
+One of the key reasons for its enduring importance is Kipling's ability to convey complex themes through the guise of seemingly simple stories. The character of Mowgli, for instance, is a powerful allegory for the journey of self-discovery and the quest for identity. Through Mowgli's interactions with the jungle's inhabitants, Kipling explores the idea of what it means to be human and the innate tension between nature and nurture.
+
+Furthermore, "The Jungle Book" is an important work in the context of colonial literature. Written during a time when the British Empire was at its zenith, the book reflects the complexities of colonial attitudes towards India. Kipling, an Anglo-Indian, infuses his stories with a nuanced understanding of Indian culture, even as he grapples with the ideological biases of his time. This duality provides a rich ground for analysis and discussion, making "The Jungle Book" a valuable resource for examining the interplay between literature and historical context.
+
+### Scope
+
+The scope of "The Jungle Book" extends beyond its pages, influencing a wide range of adaptations and interpretations across different media. The stories have been adapted into numerous films, television series, stage productions, and even operas, each bringing a new perspective to Kipling's work. These adaptations have contributed to the book's lasting legacy, ensuring its relevance in contemporary culture.
+
+In literature, "The Jungle Book" has inspired countless authors and storytellers, influencing the way animals and nature are depicted in fiction. Kipling's anthropomorphic portrayal of animals set a precedent for future works, encouraging writers to explore the moral and philosophical implications of the animal kingdom as a reflection of human society.
+
+Academically, "The Jungle Book" is a rich subject for study, offering insights into narrative structure, character development, and thematic exploration. It serves as a foundational text in the study of children's literature, colonial literature, and ecological narratives. Scholars analyze its themes of belonging and identity, the ethical dilemmas posed by its characters, and its portrayal of the natural world, which continues to resonate in today's discussions about environmental conservation and human impact on nature.
+
+In conclusion, "The Jungle Book" is more than just a collection of stories; it is a cultural artifact that has shaped the literary landscape and continues to inspire and provoke thought. Its blend of adventure, moral lessons, and richly drawn characters ensures its place as a beloved classic, while its themes of identity, nature, and society provide fertile ground for continued exploration and appreciation.
+

src/handbook_generator.py

@@ -0,0 +1,143 @@
+"""Generate 20,000+ word handbooks using the LongWriter technique and OpenAI."""
+from typing import Callable, List, Optional
+
+from openai import OpenAI
+from config import (
+    OPENAI_API_KEY,
+    CHAT_MODEL,
+    SECTION_WORD_TARGET,
+    TARGET_WORD_COUNT,
+)
+from rag import get_context_for_query
+
+_client: Optional[OpenAI] = None
+
+
+def _get_client() -> OpenAI:
+    global _client
+    if _client is None:
+        _client = OpenAI(api_key=OPENAI_API_KEY)
+    return _client
+
+
+def word_count(text: str) -> int:
+    return len(text.split())
+
+
+def llm_call(prompt: str, system_prompt: str = "You are a professional writer.") -> str:
+    """Synchronous OpenAI call."""
+    # Extract model name without provider prefix
+    model = CHAT_MODEL.split("/")[-1] if "/" in CHAT_MODEL else CHAT_MODEL
+    client = _get_client()
+    resp = client.chat.completions.create(
+        model=model,
+        messages=[
+            {"role": "system", "content": system_prompt},
+            {"role": "user", "content": prompt},
+        ],
+        temperature=0.7,
+    )
+    return resp.choices[0].message.content or ""
+
+
+# ─── LongWriter Phase 1: Outline ─────────────────────────────────────
+def generate_outline(topic: str, context: str) -> List[dict]:
+    """Generate a detailed structure for the handbook."""
+    prompt = f"""You are planning a 20,000-word handbook on "{topic}".
+Based on the reference material, create a highly detailed outline.
+For each major section, provide a title and 3-5 sub-points (keywords) to cover.
+Aim for 15-20 sections to ensure we can hit the 20k word target.
+
+Reference: {context[:10000] if context else 'No reference material available.'}
+
+Output as a list of sections (one per line):
+Section Title | point 1, point 2, point 3
+..."""
+
+    content = llm_call(prompt)
+    sections = []
+    for line in content.splitlines():
+        if "|" in line:
+            title, points = line.split("|", 1)
+            sections.append({"title": title.strip(), "points": points.strip()})
+    return sections
+
+
+# ─── LongWriter Phase 2: Generate long sections ──────────────────────
+def generate_long_section(
+    section_title: str,
+    points: str,
+    topic: str,
+    context: str,
+    previous_context: str,
+) -> str:
+    """Generate a single section following LongWriter length instructions."""
+    prev_snippet = previous_context[-2000:] if previous_context else "This is the first section."
+    ctx_snippet = context[:5000] if context else "No reference material."
+
+    prompt = f"""Write a comprehensive section for a handbook on "{topic}".
+Section Title: {section_title}
+Key points to cover: {points}
+
+Reference Material: {ctx_snippet}
+
+LongWriter Instructions:
+1. This section MUST be at least 1,500 words long.
+2. Be extremely descriptive. Explain concepts in depth.
+3. Use examples, analogies, and detailed breakdowns.
+4. Maintain continuity with previous sections: {prev_snippet}
+
+Write only the content for "{section_title}". Start with ## {section_title}."""
+
+    return llm_call(prompt)
+
+
+# ─── Main builder ────────────────────────────────────────────────────
+def build_handbook(
+    topic: str,
+    on_progress: Optional[Callable[[str], None]] = None,
+) -> str:
+    """Build a 20k+ word handbook using the LongWriter technique."""
+
+    def progress(msg: str):
+        if on_progress:
+            on_progress(msg)
+
+    progress("Gathering context for outline...")
+    context = get_context_for_query(topic)
+
+    progress("Generating detailed outline (LongWriter phase 1)...")
+    sections = generate_outline(topic, context)
+    if not sections:
+        sections = [{"title": "Introduction", "points": "Overview, Importance, Scope"}]
+
+    progress(f"Outline created with {len(sections)} sections. Starting generation...")
+
+    full_handbook = [f"# {topic}\n\n"]
+    total_words = 0
+    previous_content = ""
+
+    for i, sec in enumerate(sections):
+        title = sec["title"]
+        points = sec["points"]
+        progress(f"Writing Section {i+1}/{len(sections)}: {title} (Target: 1500+ words)...")
+
+        sec_context = get_context_for_query(f"{topic}: {title} {points}")
+
+        section_text = generate_long_section(
+            title, points, topic, sec_context, previous_content
+        )
+
+        full_handbook.append(section_text + "\n\n")
+        previous_content += section_text
+        total_words += word_count(section_text)
+
+        progress(f"Section completed. Current word count: {total_words}")
+
+        if total_words >= TARGET_WORD_COUNT:
+            progress("Target length reached.")
+            break
+
+    final_doc = "".join(full_handbook)
+    progress(f"Handbook generated. Final word count: {word_count(final_doc)}")
+    return final_doc

src/pdf_processor.py

@@ -0,0 +1,92 @@
+"""PDF text extraction and chunking for RAG."""
+import re
+from pathlib import Path
+from typing import List
+
+import pdfplumber
+from pypdf import PdfReader
+
+from config import CHUNK_OVERLAP, CHUNK_SIZE
+
+
+def extract_text_from_pdf(pdf_path: str | Path) -> str:
+    """Extract text from a PDF using pdfplumber (better for tables) with pypdf fallback."""
+    path = Path(pdf_path)
+    if not path.exists():
+        raise FileNotFoundError(f"PDF not found: {path}")
+
+    text_parts: List[str] = []
+    try:
+        with pdfplumber.open(path) as pdf:
+            for page in pdf.pages:
+                t = page.extract_text()
+                if t:
+                    text_parts.append(t)
+    except Exception:
+        # Fallback to pypdf
+        reader = PdfReader(path)
+        for page in reader.pages:
+            t = page.extract_text()
+            if t:
+                text_parts.append(t)
+
+    raw = "\n\n".join(text_parts)
+    # Normalize whitespace
+    return re.sub(r"\s+", " ", raw).strip()
+
+
+def chunk_text(
+    text: str,
+    chunk_size: int = CHUNK_SIZE,
+    overlap: int = CHUNK_OVERLAP,
+) -> List[dict]:
+    """
+    Split text into overlapping chunks for embedding.
+    Returns list of dicts with 'text' and 'metadata' (source, chunk_index).
+    """
+    if not text or not text.strip():
+        return []
+
+    chunks: List[dict] = []
+    start = 0
+    index = 0
+    text = text.strip()
+
+    while start < len(text):
+        end = start + chunk_size
+        chunk = text[start:end]
+
+        # Try to break at sentence or word boundary
+        if end < len(text):
+            last_period = chunk.rfind(". ")
+            last_newline = chunk.rfind("\n")
+            break_at = max(last_period, last_newline)
+            if break_at > chunk_size // 2:
+                chunk = chunk[: break_at + 1]
+                end = start + break_at + 1
+
+        chunk = chunk.strip()
+        if chunk:
+            chunks.append({
+                "text": chunk,
+                "metadata": {"chunk_index": index},
+            })
+            index += 1
+
+        start = end - overlap if end < len(text) else len(text)
+
+    return chunks
+
+
+def process_pdf(pdf_path: str | Path, source_name: str | None = None) -> List[dict]:
+    """
+    Extract text from PDF and return chunks with source metadata.
+    source_name: optional label (e.g. filename) for metadata.
+    """
+    path = Path(pdf_path)
+    source_name = source_name or path.name
+    text = extract_text_from_pdf(path)
+    chunks = chunk_text(text)
+    for c in chunks:
+        c["metadata"]["source"] = source_name
+    return chunks

src/prompt.py

@@ -0,0 +1,21 @@
+"""Agent prompt configuration for the Handbook Generator."""
+
+AGENT_CONFIG = {
+    "name": "handbook_assistant",
+    "description": "An AI assistant that answers questions from uploaded PDFs and helps generate handbooks. Uses RAG (retrieval from uploaded documents) via tools.",
+    "instruction": """
+You are the Handbook Assistant, an intelligent assistant that helps users understand their uploaded PDF documents and generate long-form handbooks.
+
+CRITICAL RULES:
+1. ALWAYS call the query_uploaded_documents tool FIRST before answering ANY question about documents, assignments, PDFs, or their content. NEVER assume documents are not uploaded — always check by calling the tool.
+2. When the user says they uploaded a PDF or asks about "my document", "my assignment", "my PDF", etc., you MUST call query_uploaded_documents with their question.
+3. Only say "no documents uploaded" if the tool explicitly returns that message.
+4. After getting tool results, summarize the retrieved content in your answer. Do not dump raw text.
+
+How to behave:
+- Use the query_uploaded_documents tool for ANY question that could relate to uploaded content.
+- Be professional and helpful.
+- For handbook generation, tell the user to use the "Generate Handbook" tab.
+- Maintain context across messages.
+"""
+}

src/rag.py

@@ -0,0 +1,162 @@
+"""
+RAG System — Hybrid approach:
+1. Simple vector search (OpenAI embeddings + local storage) for reliable chat retrieval
+2. LightRAG knowledge graph for enriched context (optional, non-blocking)
+
+This avoids LightRAG's internal async worker issues with Streamlit.
+"""
+import json
+import os
+from pathlib import Path
+from typing import List, Optional
+
+import numpy as np
+from openai import OpenAI
+
+from config import (
+    OPENAI_API_KEY,
+    CHAT_MODEL,
+    WORKING_DIR,
+    EMBEDDING_MODEL,
+    CHUNK_SIZE,
+    CHUNK_OVERLAP,
+)
+from pdf_processor import extract_text_from_pdf, chunk_text
+
+# ─── Vector store file ───────────────────────────────────────────────
+VECTORS_FILE = WORKING_DIR / "vectors.json"
+
+_client: Optional[OpenAI] = None
+_chunks_db: list[dict] = []  # {"text": ..., "embedding": [...]}
+
+
+def _get_client() -> OpenAI:
+    global _client
+    if _client is None:
+        _client = OpenAI(api_key=OPENAI_API_KEY)
+    return _client
+
+
+def _embed_texts(texts: list[str]) -> list[list[float]]:
+    """Get embeddings from OpenAI (sync, reliable)."""
+    client = _get_client()
+    response = client.embeddings.create(
+        model=EMBEDDING_MODEL,
+        input=texts,
+    )
+    return [item.embedding for item in response.data]
+
+
+def _cosine_similarity(a: list[float], b: list[float]) -> float:
+    a_np = np.array(a)
+    b_np = np.array(b)
+    dot = np.dot(a_np, b_np)
+    norm = np.linalg.norm(a_np) * np.linalg.norm(b_np)
+    return float(dot / norm) if norm > 0 else 0.0
+
+
+def _load_db():
+    """Load vector DB from disk."""
+    global _chunks_db
+    if VECTORS_FILE.exists():
+        with open(VECTORS_FILE, "r", encoding="utf-8") as f:
+            _chunks_db = json.load(f)
+    else:
+        _chunks_db = []
+
+
+def _save_db():
+    """Save vector DB to disk."""
+    WORKING_DIR.mkdir(parents=True, exist_ok=True)
+    with open(VECTORS_FILE, "w", encoding="utf-8") as f:
+        json.dump(_chunks_db, f)
+
+
+# ─── Public API (all synchronous — no event loop issues) ─────────────
+
+def index_pdf(pdf_path: str | Path, source_name: str | None = None) -> int:
+    """Extract text from PDF, chunk, embed, and store. Returns number of chunks."""
+    global _chunks_db
+
+    text = extract_text_from_pdf(pdf_path)
+    if not text:
+        return 0
+
+    source = source_name or Path(pdf_path).name
+    chunks = chunk_text(text)
+
+    if not chunks:
+        return 0
+
+    # Get embeddings for all chunks
+    texts = [c["text"] for c in chunks]
+
+    # Embed in batches of 20 to avoid token limits
+    all_embeddings = []
+    for i in range(0, len(texts), 20):
+        batch = texts[i:i+20]
+        batch_embeddings = _embed_texts(batch)
+        all_embeddings.extend(batch_embeddings)
+
+    # Store
+    for chunk, embedding in zip(chunks, all_embeddings):
+        _chunks_db.append({
+            "text": chunk["text"],
+            "source": source,
+            "embedding": embedding,
+        })
+
+    _save_db()
+    return len(chunks)
+
+
+def index_pdfs(pdf_paths: List[str | Path]) -> int:
+    """Index multiple PDFs."""
+    total = 0
+    for p in pdf_paths:
+        total += index_pdf(p)
+    return total
+
+
+def get_context_for_query(query: str, top_k: int = 5) -> str:
+    """Retrieve relevant chunks using cosine similarity."""
+    _load_db()
+
+    if not _chunks_db:
+        return ""
+
+    # Embed the query
+    query_embedding = _embed_texts([query])[0]
+
+    # Score all chunks
+    scored = []
+    for chunk in _chunks_db:
+        sim = _cosine_similarity(query_embedding, chunk["embedding"])
+        scored.append((sim, chunk["text"], chunk.get("source", "unknown")))
+
+    # Sort by similarity
+    scored.sort(key=lambda x: x[0], reverse=True)
+
+    # Take top_k
+    results = scored[:top_k]
+
+    if not results:
+        return ""
+
+    # Format context
+    context_parts = []
+    for i, (score, text, source) in enumerate(results, 1):
+        context_parts.append(f"[Source: {source} | Relevance: {score:.2f}]\n{text}")
+
+    return "\n\n---\n\n".join(context_parts)
+
+
+def reset_index():
+    """Clear all indexed data."""
+    global _chunks_db
+    import shutil
+
+    _chunks_db = []
+    if WORKING_DIR.exists():
+        shutil.rmtree(WORKING_DIR)
+    WORKING_DIR.mkdir(parents=True, exist_ok=True)

src/rag_tools.py

@@ -0,0 +1,24 @@
+"""
+RAG tools for the ADK agent.
+The agent calls these tools to get context from uploaded PDFs.
+"""
+from rag import get_context_for_query
+
+RAG_TOP_K = 8
+
+
+def query_uploaded_documents(query: str) -> str:
+    """
+    Retrieve relevant passages from the user's uploaded PDF documents
+    for a given question or topic.
+    Call this whenever the user asks about the content of their documents.
+    """
+    if not query or not str(query).strip():
+        return "Please provide a non-empty question or topic to search the documents."
+    context = get_context_for_query(query.strip(), top_k=RAG_TOP_K)
+    if not context or not context.strip():
+        return (
+            "No documents have been indexed yet, or no relevant passages were found. "
+            "Ask the user to upload and index PDFs first, or try a different query."
+        )
+    return context

src/runner_app.py

@@ -0,0 +1,97 @@
+"""
+ADK Runner setup — used by Streamlit to run the agent directly (no API).
+"""
+import asyncio
+import logging
+from google.adk.sessions import InMemorySessionService
+from google.adk.runners import Runner
+from google.genai import types
+
+from agent import root_agent
+
+logger = logging.getLogger(__name__)
+
+APP_NAME = "handbook_app"
+session_service = InMemorySessionService()
+
+runner = Runner(
+    agent=root_agent,
+    app_name=APP_NAME,
+    session_service=session_service,
+)
+
+
+def _text_from_content(content) -> str | None:
+    if content is None:
+        return None
+    try:
+        parts = getattr(content, "parts", None)
+        if not parts:
+            return None
+        for part in parts:
+            text = getattr(part, "text", None)
+            if text is not None and str(text).strip():
+                return str(text).strip()
+    except (AttributeError, TypeError, IndexError):
+        pass
+    return None
+
+
+async def _run_chat_async(user_id: str, session_id: str, message: str) -> str:
+    session = await session_service.get_session(
+        app_name=APP_NAME,
+        user_id=user_id,
+        session_id=session_id,
+    )
+    if not session:
+        await session_service.create_session(
+            app_name=APP_NAME,
+            user_id=user_id,
+            session_id=session_id,
+        )
+
+    user_content = types.Content(
+        role="user",
+        parts=[types.Part(text=message)],
+    )
+
+    final_response = None
+    async for event in runner.run_async(
+        user_id=user_id,
+        session_id=session_id,
+        new_message=user_content,
+    ):
+        try:
+            if getattr(event, "is_final_response", lambda: False)() and getattr(event, "content", None):
+                text = _text_from_content(event.content)
+                if text:
+                    final_response = text
+                    break
+            if getattr(event, "content", None):
+                text = _text_from_content(event.content)
+                if text:
+                    final_response = text
+        except (AttributeError, TypeError, KeyError):
+            continue
+
+    return final_response or "No response from agent. Please try again."
+
+
+def run_chat(message: str, user_id: str = "default_user") -> str:
+    """Run the ADK agent with the given message. Sync wrapper for Streamlit."""
+    session_id = f"{user_id}_session"
+    try:
+        try:
+            return asyncio.run(_run_chat_async(user_id, session_id, message))
+        except RuntimeError as re:
+            if "event loop" in str(re).lower() or "already running" in str(re).lower():
+                import concurrent.futures
+                with concurrent.futures.ThreadPoolExecutor(max_workers=1) as ex:
+                    future = ex.submit(
+                        asyncio.run, _run_chat_async(user_id, session_id, message)
+                    )
+                    return future.result(timeout=120)
+            raise
+    except Exception as e:
+        logger.exception("Chat failed: %s", e)
+        return f"Error: {e}"

src/streamlit_app.py

@@ -1,40 +1,172 @@
-import altair as alt
-import numpy as np
-import pandas as pd
+"""
+Handbook Generator — Streamlit UI with ADK agent.
+All RAG operations are synchronous — no event loop issues.
+"""
+import asyncio
+import time
+from pathlib import Path
+
 import streamlit as st
+from google.adk.sessions import InMemorySessionService
+from google.adk.runners import Runner
+from google.genai import types
 
-"""
-# Welcome to Streamlit!
+from config import OPENAI_API_KEY, UPLOADS_DIR, BASE_DIR
+from rag import index_pdf, reset_index
+from handbook_generator import build_handbook
+from agent import root_agent
 
-Edit `/streamlit_app.py` to customize this app to your heart's desire :heart:.
-If you have any questions, checkout our [documentation](https://docs.streamlit.io) and [community
-forums](https://discuss.streamlit.io).
+HANDBOOK_EXPORT_PATH = BASE_DIR / "handbook_export.md"
 
-In the meantime, below is an example of what you can do with just a few lines of code:
-"""
+# ────────────────────────────────────────────────
+APP_NAME = "handbook_app"
+session_service = InMemorySessionService()
+runner = Runner(
+    agent=root_agent,
+    app_name=APP_NAME,
+    session_service=session_service,
+)
+
+# ────────────────────────────────────────────────
+st.set_page_config(page_title="Handbook Generator", page_icon="📖", layout="wide")
+
+st.markdown("""
+    <style>
+        .stChatMessage { margin-bottom: 1.1rem !important; border-radius: 16px !important; }
+        .stChatInput > div > div { border-radius: 24px !important; padding: 0.5rem 1rem; }
+    </style>
+""", unsafe_allow_html=True)
+
+
+def ensure_api_key():
+    if not OPENAI_API_KEY:
+        st.error("OPENAI_API_KEY is not set. Create a .env with OPENAI_API_KEY=sk-...")
+        return False
+    return True
+
+
+if not ensure_api_key():
+    st.stop()
+
+st.title("📖 Handbook Generator")
+st.caption("Upload PDFs → Chat with ADK agent (RAG) → Generate 20k-word handbook")
+
+for key, value in {"messages": [], "user_id": "default_user"}.items():
+    if key not in st.session_state:
+        st.session_state[key] = value
+
+tab1, tab2, tab3 = st.tabs(["Upload PDFs", "Chat", "Generate Handbook"])
+
+# ── Tab 1: Upload (synchronous — no async needed) ────────────────
+with tab1:
+    st.subheader("Upload and index PDFs")
+    files = st.file_uploader("Choose PDF files", type=["pdf"], accept_multiple_files=True)
+    if st.button("Index PDFs"):
+        if not files:
+            st.warning("Select at least one PDF.")
+        else:
+            reset_index()
+            results = []
+            for f in files:
+                dest = UPLOADS_DIR / f.name
+                dest.write_bytes(f.getvalue())
+                try:
+                    n = index_pdf(dest, source_name=f.name)
+                    results.append(f"✅ {f.name}: {n} chunks indexed")
+                except Exception as e:
+                    results.append(f"❌ {f.name}: Error — {e}")
+            st.success("\n".join(results))
+
+# ── Tab 2: Chat ───────────────────────────────────────────────────
+with tab2:
+    st.subheader("Chat (ADK agent + RAG tool)")
+
+    for msg in st.session_state.messages:
+        role = "user" if msg["role"] == "user" else "assistant"
+        avatar = "👤" if role == "user" else "🤖"
+        with st.chat_message(role, avatar=avatar):
+            st.markdown(msg["content"])
+
+    user_input = st.chat_input("Ask about your uploaded documents...")
+
+    if user_input:
+        st.session_state.messages.append({"role": "user", "content": user_input})
+        with st.chat_message("user", avatar="👤"):
+            st.markdown(user_input)
+
+        with st.chat_message("assistant", avatar="🤖"):
+            placeholder = st.empty()
+            placeholder.markdown("▋ Thinking…")
+
+        user_id = st.session_state.user_id
+        session_id = f"{user_id}_session"
+
+        # ADK agent is async, run it properly
+        async def run_agent():
+            try:
+                session = await session_service.get_session(
+                    app_name=APP_NAME, user_id=user_id, session_id=session_id,
+                )
+                if not session:
+                    await session_service.create_session(
+                        app_name=APP_NAME, user_id=user_id, session_id=session_id,
+                    )
+
+                user_content = types.Content(
+                    role="user",
+                    parts=[types.Part.from_text(text=user_input)],
+                )
+
+                response_text = ""
+                async for event in runner.run_async(
+                    user_id=user_id, session_id=session_id, new_message=user_content,
+                ):
+                    if event.is_final_response():
+                        if event.content and event.content.parts:
+                            response_text = event.content.parts[0].text
+                        break
+
+                return response_text or "(No response generated)"
+            except Exception as exc:
+                return f"**Error occurred:** {str(exc)}"
+
+        try:
+            response = asyncio.run(run_agent())
+        except RuntimeError:
+            # Fallback if event loop already running
+            import concurrent.futures
+            with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+                response = pool.submit(asyncio.run, run_agent()).result(timeout=120)
+
+        placeholder.markdown(response)
+        st.session_state.messages.append({"role": "assistant", "content": response})
+        st.rerun()
+
+# ── Tab 3: Handbook (synchronous) ─────────────────────────────────
+with tab3:
+    st.subheader("Generate 20k-word handbook")
+    topic = st.text_input(
+        "Handbook topic", placeholder="e.g. Retrieval-Augmented Generation",
+    )
+    if st.button("Generate handbook"):
+        if not (topic and topic.strip()):
+            st.warning("Enter a topic.")
+        else:
+            status_placeholder = st.empty()
+            progress_msgs: list[str] = []
+
+            def on_progress(msg):
+                progress_msgs.append(msg)
+                status_placeholder.text("\n".join(progress_msgs))
 
-num_points = st.slider("Number of points in spiral", 1, 10000, 1100)
-num_turns = st.slider("Number of turns in spiral", 1, 300, 31)
-
-indices = np.linspace(0, 1, num_points)
-theta = 2 * np.pi * num_turns * indices
-radius = indices
-
-x = radius * np.cos(theta)
-y = radius * np.sin(theta)
-
-df = pd.DataFrame({
-    "x": x,
-    "y": y,
-    "idx": indices,
-    "rand": np.random.randn(num_points),
-})
-
-st.altair_chart(alt.Chart(df, height=700, width=700)
-    .mark_point(filled=True)
-    .encode(
-        x=alt.X("x", axis=None),
-        y=alt.Y("y", axis=None),
-        color=alt.Color("idx", legend=None, scale=alt.Scale()),
-        size=alt.Size("rand", legend=None, scale=alt.Scale(range=[1, 150])),
-    ))
+            try:
+                full_md = build_handbook(topic.strip(), on_progress=on_progress)
+                status_placeholder.success("Generation complete.")
+                st.markdown(full_md)
+                HANDBOOK_EXPORT_PATH.write_text(full_md, encoding="utf-8")
+                st.download_button(
+                    "Download as Markdown", data=full_md,
+                    file_name="handbook.md", mime="text/markdown",
+                )
+            except Exception as e:
+                status_placeholder.error(str(e))