Kythe: Autonomous Deep Research and Curriculum Engine

Kythe decomposes technical topics into structured curriculum sections, gathers web evidence using a protected deep reader, evaluates section drafts against deterministic quality gates, and exports learning dossiers in multiple formats.

Kythe manages research through an eight-stage execution lifecycle:

flowchart TD
    A["Topic or Learning Goal"] --> B["Curriculum Planner"]
    B --> C["Interactive Outline Review"]
    C -->|"Approved Outline"| D["SQLite Work-Item Queue"]
    
    subgraph Section Research Loop
        D --> E["Section Query Planner"]
        E --> F["Search & Deep Reader"]
        F -->|"SSRF-Safe Ingestion"| G["Evidence Extraction & Chunking"]
        G --> H["Section Draft Generation"]
        H --> I["Deterministic Quality Evaluator"]
        I -->|"Gaps Identified"| J["Gap Generator & Query Refinement"]
        J -->|"Retry Pass"| E
        I -->|"Passes Gate"| K["Atomic SQLite Checkpoint"]
    end

    K --> L["Master Dossier Synthesizer"]
    L --> M["Multi-Format Exporter"]
    M --> N1["Markdown Dossier"]
    M --> N2["Standalone HTML Document"]
    M --> N3["ReportLab Vector PDF"]
    M --> N4["Quiz JSON Assessment"]
    M --> N5["Flashcards JSON & CSV"]
    M --> N6["Metadata Manifest & SHA256"]

• Section Work-Item Queue: The planner breaks complex subjects into discrete modules with explicit learning objectives and target depths (basic, intermediate, or advanced).
• Protected Deep Reader: Web pages and documentation are fetched with DNS pinning, private and loopback IP blocking, streaming size caps, and content-hash caching in SQLite.
• Deterministic Quality Gates: The evaluator scores drafts on target word counts, source diversity across unique domains, code examples, citation density (<cite source="src-id"/>), and style hygiene.
• Transactional SQLite Storage: SQLite in WAL mode with compare-and-swap transitions guarantees state recovery. Paused or interrupted runs resume from the last unfinished pass without re-fetching cached evidence.
• Interactive Outline Editor: Users can modify section titles, objectives, ordering, and depth targets prior to automated execution.
• Multi-Format Exporters: Completed research outputs Markdown files, responsive HTML documents with print styling, vector PDFs with running headers, Anki flashcards, multiple-choice quiz JSON, and SHA256 checksum manifests.

git clone https://github.com/Cedsbstn/Learning-assistant-adk.git
cd learning_agent
pip install -r requirements.txt

Copy the example environment file and add your Google AI Studio API key:

cp .env.example .env

GOOGLE_API_KEY=your_google_api_key_here

# Interactive outline review with the standard preset
python main.py research "Distributed Consensus Algorithms and Raft"

# Run with the deep preset and bypass interactive outline review
python main.py research "Zero Knowledge Proofs and zk-SNARKs" --preset deep --auto-approve

# Specify custom export formats
python main.py research "Rust Memory Safety and Concurrency" --formats markdown,html,pdf,quiz,flashcards

python main.py resume run_4f89a1c2

python main.py status run_4f89a1c2

python main.py list-runs
python main.py list-runs --status completed

python main.py export run_4f89a1c2 --formats pdf,html,flashcards

Completed runs store generated assets in the output/ directory:

• curriculum_<run_id>.md: Consolidated Markdown dossier with executive summary and source bibliography.
• curriculum_<run_id>.html: Self-contained HTML file with dark mode support, keyboard navigation, and print stylesheets.
• curriculum_<run_id>.pdf: Vector PDF generated with ReportLab.
• quiz_<run_id>.json: Multiple-choice questions with answer explanations and source mappings.
• flashcards_<run_id>.json & flashcards_<run_id>.csv: Spaced-repetition cards for Anki.
• metadata_<run_id>.json: Execution audit log with section scores, token metrics, and SHA256 file checksums.

Execute the test suite with pytest:

pytest -v

Apache License 2.0. Copyright 2026 Cedric Sebastian.