WAIT — Slowing — last commit 3mo ago

• Last commit 3mo ago
• 15 active contributors
• GPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 3mo ago
• ⚠ Single-maintainer risk — top contributor 80% of recent commits
• ⚠ GPL-3.0 is copyleft — check downstream compatibility

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

GPT Academic is a specialized web interface for large language models (LLM) optimized for academic workflows: paper reading, writing, and polishing. It features modular plugin architecture supporting custom buttons, PDF/LaTeX translation and summarization, multi-model parallel querying (GPT, GLM, Qwen, DeepSeek, Claude, etc.), and local model support including ChatGLM3. The core strength is academic document processing with context-aware code analysis for Python/C++ projects. Modular plugin architecture: core entry points are config.py (configuration), core_functional.py (base functionality), and crazy_functional.py (plugin registry). Plugin implementations live in crazy_functions/ directory organized by capability (e.g., PDF_Translate.py, Paper_Reading.py, Multi_LLM_Query.py). Web frontend uses HTML/CSS/JavaScript in root-level templates; Docker support via Dockerfile for containerized deployment.

Academic researchers and students who need to interact with multiple LLM backends simultaneously for paper analysis, translation, and refinement. Also useful for developers integrating LLMs into academic workflows. Contributors are typically Chinese-speaking open-source developers extending the plugin ecosystem.

Actively developed with regular feature releases (latest: new GUI frontend in testing as of Jan 2026; major update Aug 2025). Strong community evidenced by detailed CI/CD pipelines, multiple language documentation, and 2.7M+ lines of Python code. Production-ready for academic document processing, though the 'new GUI' in beta suggests some architectural changes underway.

Large dependency footprint typical of academic AI tools (PDF processing, LaTeX, multiple API integrations) creates fragility around third-party services and Python version compatibility. Single primary maintainer (binary-husky) with significant recent activity mitigates abandonment risk but concentrates knowledge. Breaking changes possible during GUI migration; pin exact versions as per Jan 2024 advisory in README.

New GUI frontend in active testing (master branch, Jan 2026). Recent optimizations to Docker build efficiency (Aug 2025). Feature additions around Qwen2.5-Max integration (Feb 2025) and custom font support (Feb 2025). GitHub Actions workflows building multiple capacity variants (with/without audio, LaTeX, local LLMs).

git clone https://github.com/binary-husky/gpt_academic.git
cd gpt_academic
pip install -r requirements.txt
python check_proxy.py
# Edit config.py with your API keys
python main.py  # or through Docker: docker build -t gpt-academic . && docker run -it gpt-academic

Daily commands:

# Check proxy configuration
python check_proxy.py

# Development run
python main.py

# Docker run (see Dockerfile)
docker build -f Dockerfile -t gpt-academic .
docker run -it -v $(pwd):/workspace gpt-academic

• config.py — Central configuration file that manages all LLM API keys, model selections, proxy settings, and feature flags—every contributor must understand config inheritance and environment variable precedence
• core_functional.py — Core prompt templates and functional definitions for academic tasks (translation, summarization, polishing)—the foundation for all LLM interactions
• crazy_functional.py — Router and loader for all plugin functions—defines how custom functions are discovered, registered, and executed; critical for the plugin architecture
• crazy_functions/__init__.py — Plugin system initialization and registration—all new features plug through this module
• crazy_functions/crazy_utils.py — Shared utilities for file I/O, LLM API calls, token counting, and document processing—used across all crazy functions
• crazy_functions/doc_fns/text_content_loader.py — Unified document loader for PDF, Word, Excel, Markdown—handles format-agnostic content extraction for RAG and document processing
• crazy_functions/Helpers.py — Helper wrappers for LLM API integrations and model management—abstracts model-specific differences (OpenAI, Claude, Qwen, etc.)

Add a New Core Academic Function

1. Define the prompt template in core_functional.py with a unique function_id (core_functional.py)
2. Add the function to the FUNCTIONS dict, specifying input format and button label (core_functional.py)
3. Verify the function is auto-loaded in the main UI (typically no UI code needed; Gradio binds dynamically) (crazy_functional.py)

Add a New Plugin Function (Crazy Function)

1. Create a new .py file in crazy_functions/ with a function following the signature: def func_name(txt, llm_kwargs, file_list, chatbot, history, system_prompt, web_port) (crazy_functions/Interactive_Func_Template.py)
2. Import and register the function in crazy_functional.py's plugin loader (crazy_functional.py)
3. Use crazy_utils helper functions (e.g., request_gpt_model_in_new_thread()) for LLM calls (crazy_functions/crazy_utils.py)
4. Add input/output documentation via function docstring; UI will auto-generate button labels (crazy_functions/Interactive_Func_Template.py)

Add Support for a New LLM Model

1. Add model name, API endpoint, and credentials to config.py (or environment variables) (config.py)
2. Create or update an LLM wrapper in crazy_functions/Helpers.py (if not already abstracted) (crazy_functions/Helpers.py)
3. Register the model in the LLM router within Helpers.py or a dedicated model adapter module (crazy_functions/Helpers.py)
4. Test via Multi_LLM_Query or by setting the model in config and running a core function (crazy_functions/Multi_LLM_Query.py)

Add Document Format Support for RAG/Processing

1. Create a new reader in crazy_functions/doc_fns/read_fns/ (e.g., csv_reader.py) that implements text extraction (crazy_functions/doc_fns/read_fns/__init__.py)
2. Register the reader in the dispatcher module; map file extension to reader function (crazy_functions/doc_fns/text_content_loader.py)
3. Update text_content_loader.py to detect the new format and route to your reader (crazy_functions/doc_fns/text_content_loader.py)
4. Optionally add a conversation document exporter in doc_fns/conversation_doc/ if output format is needed (crazy_functions/doc_fns/conversation_doc/__init__.py)

• Gradio Web UI — Zero-config web interface for rapid prototyping; auto-generates UI from Python functions; minimal frontend code overhead
• Plugin/Modular Architecture — Decouples domain functions (PDF analysis, code review, translations) into standalone modules; enables community contributions without core codebase changes
• Multi-LLM — undefined

API Key Setup Required: No default keys; config.py must be populated with actual credentials before first use (check check_proxy.py first to validate network). Exact Version Pinning: README explicitly warns (Jan 2024) to use exact versions from requirements.txt—pip's default behavior will break. Proxy Configuration: Academic institutions often behind proxies; check_proxy.py must pass or plugin execution fails silently. PDF Processing Dependencies: Some workflows (LaTeX, PDF extraction via Nougat) require system-level deps (texlive, OCR libraries) not in pip—see Docker variants for reference. Token/Context Limits: Each LLM backend has different context windows; long document chunking in Helpers.py is aggressive but may still overflow smaller models. Async Event Loop: Some plugins use generators with async I/O; running in Jupyter/IPython may require event loop management.

• Prompt Engineering for Academic Context — This repo's core strength is task-specific prompts for paper reading/writing; understanding how core_functional.py constructs domain-aware system prompts is critical to extending the system effectively
• Document Chunking with Context Preservation — Academic documents (PDFs, LaTeX) exceed LLM context windows; the chunking strategy in crazy_functions/Helpers.py must preserve semantic boundaries—misunderstanding this breaks paper translation quality
• Streaming API Responses — Long LLM outputs (paper summaries, translations) are streamed to users via generators in core_functional.py; understanding Python generators and async streaming is needed for plugin development
• Plugin Factory Pattern — The crazy_functional.py registry dynamically loads plugins from crazy_functions/; understanding how Python's importlib and function introspection work here is essential for adding new capabilities
• Multi-Model Parallel Execution — The differentiator feature (Multi_LLM_Query.py) queries multiple backends concurrently; understanding async concurrency patterns and callback management is needed to extend this capability
• LaTeX and PDF Processing Pipelines — Several plugins (Latex_Function.py, PDF_Translate.py) interface with external tools (pdflatex, pymupdf); understanding subprocess management, binary dependencies, and format conversion is needed for academic document workflows
• API Key Management and Proxy Configuration — The project supports 10+ LLM backends with different auth schemes; config.py and check_proxy.py handle credential routing and network constraints—critical for academic environments behind institutional proxies

• LAVIS-Project/LAVIS — Similar academic document understanding focus; LAVIS provides vision-language models for paper figure analysis that could enhance gpt_academic's PDF capabilities
• openai/openai-python — Official OpenAI SDK that gpt_academic wraps; understanding its streaming API is essential for extending model support
• gradio-app/gradio — Web UI framework underlying gpt_academic's interface; knowledge of Gradio's component model needed for custom frontend modifications
• ollama/ollama — Local LLM runtime that gpt_academic integrates with for running models like ChatGLM3 offline; ecosystem companion for deployment
• langchain-ai/langchain — Document processing and RAG framework that implements similar chunking/context patterns to those in gpt_academic's Helpers.py and PDF plugins

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for crazy_functions module plugins

The repo has 40+ plugin files in crazy_functions/ but no visible test suite. This is critical for a plugin-based architecture where contributors add custom functions. Testing individual plugins (PDF_QA.py, SourceCode_Analyse.py, etc.) would prevent regressions and make contributions safer.

• [ ] Create tests/ directory with pytest structure mirroring crazy_functions/
• [ ] Add unit tests for crazy_functions/PDF_QA.py covering document parsing edge cases
• [ ] Add unit tests for crazy_functions/SourceCode_Analyse.py with sample code snippets
• [ ] Add integration tests for crazy_functions/Multi_LLM_Query.py mock LLM responses
• [ ] Configure pytest in GitHub Actions workflow (add to .github/workflows/)

Create API documentation for plugin development using mkdocstrings

The repo has mkdocs/mkdocstrings dependencies configured but no docs/ folder visible in the file structure. With 40+ crazy_functions and agent_fns, contributors need clear API docs. The Interactive_Func_Template.py suggests a plugin interface that should be documented.

• [ ] Create docs/ folder with mkdocs.yml configuration
• [ ] Add docs/plugins/template.md explaining the plugin interface using Interactive_Func_Template.py as example
• [ ] Add docs/plugins/examples.md with working examples from PDF_Translate.py, SourceCode_Comment.py
• [ ] Configure mkdocstrings in mkdocs.yml to auto-generate API docs from docstrings in agent_fns/
• [ ] Add GitHub Action to deploy docs to GitHub Pages on push to master

Add GitHub Actions workflow for testing Docker builds across supported platforms

The repo has 5 Dockerfile variants (build-with-latex.yml, build-with-audio-assistant.yml, etc.) but no validation that they all successfully build. The recent note about 'Dockerfile构建效率大幅优化' suggests ongoing Docker work. A comprehensive multi-platform build test would catch regressions early.

• [ ] Create .github/workflows/docker-build-test.yml that builds all 5 Dockerfile variants
• [ ] Add matrix testing for platforms: linux/amd64, linux/arm64 (for raspberry pi users mentioned implicitly)
• [ ] Add step to verify base images are cached/optimized (check build time output)
• [ ] Include smoke tests: verify key executables exist in built images (check python, ffmpeg for Audio_Assistant variant)
• [ ] Add workflow trigger on: changes to any Dockerfile, requirements.txt, or pyproject.toml files

• Add unit tests for crazy_functions/Helpers.py document chunking logic—currently no test coverage for edge cases (very long documents, unicode handling, boundary preservation)
• Create comprehensive documentation for the plugin template in crazy_functions/Interactive_Func_Template.py with worked examples showing how to implement a new document-processing plugin from scratch
• Implement missing error handling and retry logic in core_functional.py for API timeout/rate-limit scenarios—currently relies on raw exception propagation with poor UX feedback

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/binary-husky/gpt_academic shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live binary-husky/gpt_academic repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/binary-husky/gpt_academic.

What it runs against: a local clone of binary-husky/gpt_academic — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in binary-husky/gpt_academic | Confirms the artifact applies here, not a fork | | 2 | License is still GPL-3.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 134 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of binary-husky/gpt_academic. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/binary-husky/gpt_academic.git
#   cd gpt_academic
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of binary-husky/gpt_academic and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "binary-husky/gpt_academic(\\.git)?\\b" \\
  && ok "origin remote is binary-husky/gpt_academic" \\
  || miss "origin remote is not binary-husky/gpt_academic (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(GPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"GPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is GPL-3.0" \\
  || miss "license drift — was GPL-3.0 at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "config.py" \\
  && ok "config.py" \\
  || miss "missing critical file: config.py"
test -f "core_functional.py" \\
  && ok "core_functional.py" \\
  || miss "missing critical file: core_functional.py"
test -f "crazy_functional.py" \\
  && ok "crazy_functional.py" \\
  || miss "missing critical file: crazy_functional.py"
test -f "crazy_functions/__init__.py" \\
  && ok "crazy_functions/__init__.py" \\
  || miss "missing critical file: crazy_functions/__init__.py"
test -f "crazy_functions/crazy_utils.py" \\
  && ok "crazy_functions/crazy_utils.py" \\
  || miss "missing critical file: crazy_functions/crazy_utils.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 134 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~104d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/binary-husky/gpt_academic"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.