Pi_zaya

English | 简体中文

Pi_zaya is a local-first, evidence-grounded reading assistant for academic PDFs. It helps users read papers already in their library, retrieve and compare evidence, trace citations to the source, verify claims, and organize source-backed notes and evidence matrices.

Pi_zaya does not draft, rewrite, or polish manuscripts and is not a submission preparation tool. Answers use only the library by default. Per conversation, users can explicitly allow model knowledge or web search to supplement an answer only when local evidence is insufficient.

The product entry is FastAPI + React. The legacy Streamlit entry has been removed; do not use app.py, streamlit run, or port 8501 as the product entry.

Downloadable Windows beta

The current published Windows beta is v0.1.0-beta.13.

The local development candidate is 0.1.0-beta.14, not yet published. Its artifact names are Pi_zaya-v0.1.0-beta.14-windows-x64-setup.exe and Pi_zaya-v0.1.0-beta.14-windows-x64.zip; the public download links below remain beta.13.

Choose the right download

Release file	Who should use it	How to use it
Pi_zaya-v0.1.0-beta.13-windows-x64-setup.exe	Recommended for most Windows users	Verify its checksum, run Setup, then open Pi_zaya from the Start menu or optional desktop shortcut. It installs for the current user without administrator privileges.
Pi_zaya-v0.1.0-beta.13-windows-x64.zip	Portable use, removable folders, or troubleshooting	Verify its checksum, extract the entire archive into a normal folder, then double-click Pi_zaya.exe.
*.sha256	Anyone verifying a download	This is a text checksum file, not an application. Compare it with Get-FileHash <download> -Algorithm SHA256.
*.manifest.json	Auditors and advanced users	This is machine-readable build provenance, commit, license, package type, and signing status. It is not an application.
GitHub-generated “Source code” archives	Developers only	These contain repository source and are not ready-to-run Windows packages. Use the installer or portable ZIP unless you intend to build from source.

Both application packages include an embedded Python runtime and prebuilt React frontend, so Node.js, system Python, and npm are not required. The installed Start menu entry or portable Pi_zaya.exe opens the local app in the default browser and remains available from the system tray. If the preferred loopback port is occupied, the launcher selects another local port automatically.

User databases, PDFs, converted Markdown, preferences, backups, and logs live under %LOCALAPPDATA%\Pi_zaya, separate from the installed or extracted program folder. In-place installation, uninstall, and portable-folder replacement do not delete the library. Read the packaged README-中文.md or the repository Chinese Windows guide for API/model setup, conversion recovery, updating, uninstalling, and checksum instructions.

The source and release artifacts are available under the MIT License. The published beta passed the complete Windows packaging and packaged-runtime gates. PDF conversion jobs are persisted in the local library database. If Pi_zaya is stopped during conversion, the Library shows an interrupted task after restart and waits for the user to continue it; completed page-cache artifacts are reused. Automatic updates are not implemented. Unless the release manifest says signed: true and Windows validates the named publisher, the installer and launcher are unsigned. These boundaries keep the release explicitly beta rather than a general-availability desktop product.

Problem

Academic PDF QA demos often fail in the places researchers care about most:

• They answer without showing which paper passage supports the claim.
• They blur paper-specific findings with general model knowledge.
• They do not expose retrieval scope, tool steps, or citation confidence.
• They treat PDF conversion, reference metadata, and answer grounding as separate demos instead of one workflow.

Pi_zaya is designed around the opposite constraint: if an answer claims something about a paper, the user should be able to trace that claim back to local evidence or see a clear disclosure that the answer used external model or web context.

Key Features

Capability	What it provides
Anchored PDF conversion	Converts PDFs to Markdown while preserving page markers, sections, figures, formulas, and source anchors.
Restart-safe conversion	Persists queued and active conversion jobs, offers explicit recovery after restart, and reuses completed page-cache artifacts without automatically spending model credits.
Evidence-based QA	Searches the indexed library, builds a RAG prompt from retrieved snippets, and returns grounded answers.
Optional local semantic retrieval	After explicit consent, installs a separately verified local component and combines BM25 with local dense retrieval for the current paper or selected basket. The local beta.14 portable candidate bundles the archive for offline installation. BM25 remains the default and the full-library path.
Citation tracing	Surfaces answer evidence, source cards, reference context, and reader locate targets.
Literature basket	Lets users collect papers and excerpts, keep local research context, and export citations.
Research notes workspace	Saves exact source-backed text, table, equation, and figure captures with paper links, comments, tags, search, pinning, archiving, and return-to-source navigation. Markdown and Word exports are backups for continued reading and evidence review, not submission-ready documents.
Internal evidence matrices	Available only in explicitly enabled internal builds; hidden in ordinary downloads, along with dependent brief/gap/project-status entrances. Retained for development and compatibility testing.
Supplement source choice	Uses the library only by default. Users may select model or web supplementation per conversation; either is used only after insufficient local evidence, and web failure never silently substitutes model knowledge.
Research Agent	Applies planning, source policy, tool-use tracing, evidence sufficiency, and sentence-level citation support checks by default.
Quality tooling	Scans conversion quality, runs repair flows, rebuilds indexes, and tracks metadata/reference sync.

Architecture

flowchart LR
  A["PDF Library"] --> B["PDF-to-Markdown Converter"]
  B --> C["Chunking + Structured Index"]
  C --> D["BM25 + Structured Retrieval"]
  D --> E["Research Agent Runtime"]
  E --> P["Planner + Intent Router"]
  E --> R["Evidence Retriever"]
  E --> X["Reference Resolver"]
  E --> G["Reading Guide Tool"]
  E --> M["Paper Comparison Tool"]
  E --> Q["Research Run + Transient Evidence Matrix"]
  E --> V["Claim Verifier"]
  L["Project Literature Basket"] --> EM["Persistent Evidence Matrix"]
  P --> O["Grounded Answer + Citation Trace UI"]
  R --> O
  X --> O
  G --> O
  M --> O
  Q --> O
  V --> O
  EM --> O

Loading

At a high level:

1. PDFs are converted into anchored Markdown with page markers and source locations.
2. Markdown is chunked and indexed for retrieval, references, figures, and reader navigation.
3. Retrieval returns candidate evidence under the current-paper, basket, or full library scope.
4. The Research Agent plans tool calls, checks evidence sufficiency, generates an answer, and verifies citation support by default. Model or web supplementation is considered only after an explicit user choice and only when local evidence is insufficient.
5. A project can turn selected literature-basket sources into a persistent, versioned evidence matrix. Each populated factual cell is an extract from the same paper and carries a reader locator; missing evidence stays visibly empty.
6. The frontend keeps the answer clean while citations, reference cards, reader locate targets, and agent traces remain inspectable on demand.

The published beta.13 retrieves candidates with BM25, query translation/expansion, and structured indexes. The local development tree contains the next Windows build's explicit opt-in local semantic path: a separately verified component maintains an atomic local embedding index and combines BM25 with dense retrieval for current-paper and selected-basket queries. It never enables web or model knowledge, never uploads library content for retrieval, fails open to BM25, and leaves full-library retrieval on BM25. This is an exact local index, not an external vector database, and has not been backported to beta.13.

The local beta.14 portable candidate includes the verified component archive. Open the retrieval control, choose Enable local semantic retrieval, confirm Install and enable, and wait for the local index to become ready before selecting hybrid retrieval. Component installation in this bundled build needs no download; answer generation still uses the configured model API. The archive adds about 286 MiB to the package and installs about 514 MiB before index/cache overhead. Installation and indexing remain explicit user actions.

Key backend entry points:

• api/main.py: FastAPI application
• api/routers/generate.py: streaming chat generation
• api/routers/chat.py: conversations, messages, uploads, and direct research-agent endpoint
• api/routers/library.py: library, conversion, quality, metadata, and indexing APIs
• api/routers/evidence_matrices.py: project evidence-matrix generation, revisions, cell audit, and export
• kb/task_runtime.py: background generation/conversion runtime
• kb/evidence_matrix.py: source-balanced cell extraction, strict same-source repair, comparison boundaries, audit, and exporters
• kb/agent/: lightweight Research Agent layer

Key frontend entry points:

• web/src/main.tsx: React entry
• web/src/pages/ChatPage.tsx: main chat workspace
• web/src/pages/LibraryPage.tsx: PDF/library workspace
• web/src/components/chat/AgentTracePanel.tsx: Research Agent trace UI
• web/src/components/chat/CiteShelf.tsx: literature basket UI
• web/src/components/chat/EvidenceMatrixWorkspace.tsx: persistent matrix editor, evidence, versions, and exports
• web/src/api/*.ts: typed API contracts

Research Agent and supplement sources

The Research Agent is the default Q&A runtime. It does not replace retrieval, prompt building, or citation cards. A response can include an agent_trace object with:

• question_type: single_paper_qa, multi_paper_comparison, reading_guide, reference_followup, or unknown
• context.planner_intent: typed planner output with task type, required tools, evidence need, target-paper hints, and planner confidence
• context: effective query scope, requested scope, current-paper lock, and selected-basket count when available
• summary: compact audit fields for claim support, scope, tool-call count, and error presence
• research_run: compact run metadata with source policy, subtask summary, and evidence-matrix rows for paper, method, result, limitation, quote, and support status
• plan: planned steps with goal, tool, and status
• steps: executed tool calls, observations, compact outputs, and errors
• verification: sentence-level citation/evidence support counts, evidence_status (grounded, needs_review, insufficient, or not_applicable), unsupported-claim reasons, and compact matched evidence sources

For reference-followup answers, resolved upstream references in the trace can be opened in the reader or added to the literature basket from the chat UI. For comparison and evidence-heavy answers, the trace can include a compact evidence matrix so reviewers can scan which source supports which method, result, or limitation without exposing raw tool logs in the main answer. The same matrix is also attached to the pre-answer structured notes, so answer generation can synthesize from the paper/method/result/limitation/evidence cells instead of treating the matrix as UI-only audit metadata. Historical agent traces can also be read through the compact audit endpoint GET /api/messages/{message_id}/agent-trace. The React UI keeps this as a collapsed, on-demand trace panel so ordinary answers are not crowded with planning or tool-log details. When opened, the panel shows the compact summary first; plan and tool-call logs stay behind a second "Execution Details" disclosure. When collapsed, the panel only shows compact evidence-check status and scope, not raw question-type labels or tool execution logs. The runtime also applies a lightweight evidence gate. Local snippets remain the authority whenever they are sufficient. The composer stores one supplement choice per conversation:

• Library only (default): state that evidence is insufficient without adding external knowledge.
• Model supplement: allow model knowledge only after insufficient local evidence; never run web search.
• Web supplement: try configured web search only after insufficient local evidence; if it is unavailable or fails, never substitute model knowledge.

Web search has a separate enable switch, API key, base URL, and model in Settings. The composer checks that capability before sending, and opens the matching settings card when a saved web choice is not ready. External and hybrid answers are visibly marked so users can tell which claims are library-grounded and which parts use explicitly requested model or web context. Linked web sources remain in a separate external-source section: they can be opened, but they cannot enter the literature basket or be saved as verified evidence notes. For hybrid answers, users can still save the individual library citation cards. The source blend is explicit in the trace: local_grounded, hybrid_local_external, external_academic, or general_llm. General non-library questions can use the normal text API without adding a knowledge-base miss notice to the answer. After generation, a lightweight answer-quality gate checks citation presence, source disclosure, evidence overlap, and trace/debug leakage. If the answer fails, the runtime makes one repair attempt; if it still cannot pass, it returns a conservative evidence-only summary instead of exposing unsupported claims. The main answer body is kept focused on the response and necessary citations in rendered UI, API streaming, and stored chat messages; trace JSON, plan steps, tool calls, and verification details remain behind the trace panel.

The planner uses simple heuristics first:

• comparison keywords -> multi_paper_comparison
• "how to read" / reading-guide language -> reading_guide
• reference, citation, upstream, prior-work language -> reference_followup
• otherwise -> single_paper_qa

Low-confidence retrieval hits are preserved in the trace for diagnosis, but only usable hits are treated as local evidence. External supplementation is routed only when the saved user choice permits it; it is never presented as a knowledge-base-grounded result.

The tool layer wraps existing modules instead of adding external services:

• retrieve_evidence
• retrieve_references, which reads the local reference index when available and returns compact upstream-reference fields such as ref_num, title, authors, year, doi, source_paper, and why_relevant
• build_reading_guide
• compare_papers, which returns source-specific paper, method, evidence, limitation, and relation_to_question fields
• generate_grounded_answer
• verify_answer_citations

If no text LLM API key is configured, the agent still runs in degraded mode and returns retrieved evidence notes plus a trace instead of crashing the app.

Select a supplement source

Use the supplement-source dropdown in the React composer. The choice is persisted per conversation and applies only to newly sent turns. Deep links may use /?external_supplement=model or /?external_supplement=web; omitting the parameter keeps the safe Library only default.

API options:

POST /api/generate
Content-Type: application/json

{
  "conv_id": "conversation-id",
  "prompt": "Compare these papers",
  "agent_mode": true,
  "external_supplement_mode": "disabled",
  "query_scope": "basket",
  "prompt_context": {
    "items": [
      {"title": "Paper A", "sourcePath": "paper-a.md"}
    ]
  }
}

Direct non-conversation endpoint:

POST /api/chat/research-agent
Content-Type: application/json

{
  "query": "How should I read this paper?",
  "top_k": 6,
  "external_supplement_mode": "disabled",
  "query_scope": "current_paper",
  "source_lock_path": "converted-paper.md"
}

Supported query_scope values are current_paper, basket, and library. The low-level generation API remains backward-compatible: omitting agent_mode, or setting it to false, keeps the legacy non-Agent path. The React product UI sends agent_mode: true and uses Library only by default.

Source development quick start

This section is for contributors running the repository source. Users of the Windows installer or portable ZIP do not need Python, Node.js, or npm.

Requirements:

• Python 3.10.11 as declared in .python-version
• Node.js 24.13.0 as declared in .nvmrc
• At least one text LLM key for full answers: QWEN_API_KEY, DEEPSEEK_API_KEY, or OPENAI_API_KEY

Install:

Copy-Item .env.example .env

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

cd web
npm ci
cd ..

Run the development UI and API:

.\run_new.ps1 -StopExisting

Equivalent wrapper:

.\run.ps1 -StopExisting

Primary local URLs:

• React app: http://127.0.0.1:5173/
• FastAPI backend: http://127.0.0.1:8000/

Run backend only:

python -m uvicorn api.main:app --host 127.0.0.1 --port 8000 --reload

Run frontend only:

cd web
npm run dev -- --host 127.0.0.1 --port 5173

Build frontend:

cd web
npm run build

Single-service local production mode:

cd web
npm run build
cd ..
python server.py

Production Deployment

For public deployments, keep user-facing login disabled while protecting management writes:

Set KB_PRIVATE_INSTANCE_AUTH=0, KB_ENABLE_AUTH_GATE=0, and KB_REQUIRE_AUTH=0 so ordinary users can open the app without an access token. Set KB_REQUIRE_MANAGEMENT_AUTH=1 and configure KB_MANAGEMENT_ACCESS_TOKEN or KB_MANAGEMENT_ACCESS_TOKEN_SHA256 so settings, uploads, library changes, conversion, and reindex operations require the owner token. The Settings drawer contains the management unlock control.

Chinese deployment note: 面向普通用户的公开部署保持 KB_PRIVATE_INSTANCE_AUTH=0、KB_ENABLE_AUTH_GATE=0 和 KB_REQUIRE_AUTH=0，用户打开应用不需要访问令牌；同时设置 KB_REQUIRE_MANAGEMENT_AUTH=1 与管理令牌，设置、上传、文献库修改、转换和重建索引需要管理员解锁。

Use private/internal auth only for controlled instances, and configure KB_ACCESS_TOKEN or KB_ACCESS_TOKEN_SHA256 when auth is enabled.

Run the production readiness check after startup:

python tools\check_production_readiness.py --base-url http://127.0.0.1:8000

Configuration

Common environment variables:

• QWEN_API_KEY, DEEPSEEK_API_KEY, or OPENAI_API_KEY: text model access
• QWEN_BASE_URL, DEEPSEEK_BASE_URL, OPENAI_BASE_URL: optional provider base URLs
• QWEN_TEXT_MODEL, QWEN_VISION_MODEL: separate Qwen text and PDF-conversion model names
• QWEN_MODEL, DEEPSEEK_MODEL, OPENAI_MODEL: optional legacy/shared model names (QWEN_MODEL remains a backward-compatible override)
• KB_AGENT_WEB_SEARCH_ENABLED: enable or disable no-hit academic web fallback
• KB_AGENT_WEB_SEARCH_API_KEY: optional OpenAI-compatible web-search key; falls back to OPENAI_API_KEY
• KB_AGENT_WEB_SEARCH_MODEL: web-search model, default gpt-5-search-api
• KB_PDF_DIR: source PDF directory
• KB_MD_DIR: converted Markdown directory
• KB_DB_DIR: retrieval/index directory
• KB_CHAT_DB: chat SQLite path
• KB_LIBRARY_DB: library SQLite path
• KB_CROSSREF_BUDGET_S: Crossref sync time budget

For local development, copy the development environment template:

Copy-Item .env.example .env

Copy the production environment template only for production-style deployment:

Copy-Item .env.production.example .env

The settings UI can also store local API preferences in user_prefs.json. Environment variables and .env values take precedence.

Typical Workflow

1. Open the Library page.
2. Upload or select PDFs.
3. Convert PDFs to Markdown.
4. Review conversion quality and run repair/reconversion when needed.
5. Rebuild the knowledge base indexes.
6. Ask questions from the current paper, selected literature basket, or full library.
7. Open answer evidence/citation cards in the Reader.
8. Select source text or use a table, equation, or figure action in the Reader to add the exact located evidence and your comment to a new or existing research note.
9. Add important papers and excerpts to a literature basket and continue asking questions within the selected source scope.
10. Save and export source-backed reading notes for continued reading and evidence review.

Demo

A polished demo GIF/video is not checked into the repository yet. Suggested demo path for portfolio use:

1. Upload one or two academic PDFs.
2. Convert and index the papers.
3. Ask a paper-specific question with the default Library only source policy.
4. Open the citation card and reader locate target.
5. Ask a comparison or reading-guide question.
6. Open the Research Agent Trace panel to show planner intent, tool calls, evidence matrix, evidence status, and claim verification.

Development and testing

• Development: LittlePyx
• Testing: Izaya

License

Pi_zaya is licensed under the MIT License. See LICENSE.

Evaluation

See docs/EVAL_DASHBOARD.md for metric categories, manual/semi-automated evaluation tables, commands, current limitations, and future work. The document intentionally does not include fabricated numbers.

Core evaluation dimensions:

• Retrieval Recall@k and retrieval relevance
• Citation precision and evidence locate success
• Claim support rate and unsupported claim rate
• No-evidence refusal accuracy
• Agent trace completeness, evidence-matrix coverage, and planner accuracy
• P50/P95 latency and cost per query when instrumentation is available

Metrics remain TBD until produced by a reproducible run or documented manual review. The lightweight agent trace eval can write a JSON report with measured fixture-regression fields and null placeholders for unmeasured live metrics such as latency and cost.

The recorded fixture docs/research_agent_eval_v1.jsonl checks a small set of answer-quality guardrails: local-evidence support, hybrid/external source disclosure, expected answer-point coverage, and keeping trace/tool/debug content out of the main answer. Treat these as reproducible regression checks, not as a claimed live benchmark.

Useful commands:

python -m pytest tests/unit -q
python -m ruff check .
python -m pytest tests/unit/test_agent_answer_runtime_e2e.py -q
python tools\research_qa\validate_research_agent_golden.py
python tools\research_qa\run_agent_trace_eval.py --json-out test_results\agent_trace_eval.json
python tools\research_qa\export_research_agent_samples.py --db chat.sqlite3 --out test_results\research_agent_answer_samples.jsonl --limit 50
python tools\research_qa\review_research_agent_samples.py prepare --samples test_results\research_agent_answer_samples.jsonl --labels test_results\research_agent_answer_labels.jsonl
python tools\research_qa\review_research_agent_samples.py merge --samples test_results\research_agent_answer_samples.jsonl --labels test_results\research_agent_answer_labels.jsonl --out test_results\research_agent_answer_reviewed.jsonl
python tools\research_qa\run_agent_trace_eval.py --real-samples test_results\research_agent_answer_samples.jsonl --json-out test_results\agent_trace_real_replay_eval.json
python tools\research_qa\run_reviewed_replay_eval.py
python tools\research_qa\run_research_qa_eval.py --dry-run
python tools\research_qa\run_research_qa_eval.py --suite full_library_acceptance_v1 --dry-run
python tools\research_qa\run_research_qa_eval.py --validate-sources --db-root db
python tools\converter_quality\run_converter_quality_eval.py --dry-run

cd web
npm run lint
npm run build
npm run test:e2e:smoke

GitHub Actions runs these as separate frontend, backend, and quality_gates jobs, with build_and_test kept as a final summary check for branch-protection compatibility. Shared backend CI setup lives in .github/actions/setup-backend-python; pinned CI-only Python tools live in requirements-ci.txt. Ruff initially gates syntax errors and undefined names, so existing style debt can be reduced incrementally without weakening the gate.

Data Files

Local runtime data is not intended for Git commits:

Path	Purpose
chat.sqlite3	Conversations, messages, message refs, and chat metadata
library.sqlite3	Library metadata and source tracking
db/	Docs, chunks, reference index, and Crossref cache
backups/	Manual and automatic backups

Development Notes

• Preserve Markdown page markers like <!-- kb_page: N -->.
• Keep React API contracts typed in web/src/api.
• Prefer fixing quality issues in converter/retrieval/data flow code instead of only hiding UI states.
• Keep background and shared state thread-safe.
• Before high-risk operations, create or verify a backup.

Roadmap

• Add a small labeled QA benchmark with expected evidence and manual rubric notes.
• Track retrieval/citation/claim metrics over time in JSON reports.
• Improve intent routing beyond keyword heuristics while keeping degraded mode.
• Add optional answer repair passes for unsupported claims.
• Add a demo video and curated portfolio walkthrough.
• Explore a future MCP-compatible local tool server for paper search, chunk reading, reference resolution, and citation-grounded exports.

Portfolio / Interview Talking Points

• Local-first architecture: papers, indexes, references, and chat state are stored locally instead of requiring a hosted document service.
• Evidence grounding: answers are designed around citations, reader locate targets, and claim-level support checks.
• Agent runtime: explicit planner intent, tool calls, evidence sufficiency, and trace UI sit on top of the RAG pipeline.
• Production concerns: FastAPI + React architecture, typed frontend API contracts, background queues, SQLite stores, CI, unit/sanity/e2e tests, and degraded-mode behavior when LLM keys are missing.
• Evaluation honesty: docs and scripts expose evaluation dimensions without inventing benchmark numbers.

Suggested GitHub Metadata

Repository description:

Local-first evidence-grounded research agent for academic PDFs with RAG, citation tracing, agent planning, and verifiable answers.

Suggested topics:

ai-agent, rag, llm, research-agent, fastapi, react, typescript, pdf-processing, citation-tracing, agent-observability, llm-evaluation