PocketFlow-Tutorial-Codebase-Knowledge README

The project's README from github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge. As one markdown file: README.md.

Turns Codebase into Easy Tutorial with AI

License: MIT

Ever stared at a new codebase written by others feeling completely lost? This tutorial shows you how to build an AI agent that analyzes GitHub repositories and creates beginner-friendly tutorials explaining exactly how the code works.

This is a tutorial project of Pocket Flow, a 100-line LLM framework. It crawls GitHub repositories and builds a knowledge base from the code. It analyzes entire codebases to identify core abstractions and how they interact, and transforms complex code into beginner-friendly tutorials with clear visualizations.

  🔸 🎉 Reached Hacker News Front Page (April 2025) with >900 up‑votes: Discussion »

🤯 All these tutorials are generated entirely by AI by crawling the GitHub repo!

🚀 Getting Started

  1. Clone this repository

    git clone https://github.com/The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge

  2. Install dependencies:

    pip install -r requirements.txt

  3. Set up LLM in utils/call_llm.py by providing credentials. To do so, you can put the values in a .env file. By default, you can use the AI Studio key with this client for Gemini Pro 2.5 by setting the GEMINI_API_KEY environment variable. If you want to use another LLM, you can set the LLM_PROVIDER environment variable (e.g. XAI), and then set the model, url, and API key (e.g. XAI_MODEL, XAI_URL,XAI_API_KEY). If using Ollama, the url is http://localhost:11434/ and the API key can be omitted. You can use your own models. We highly recommend the latest models with thinking capabilities (Claude 3.7 with thinking, O1). You can verify that it is correctly set up by running:

    python utils/call_llm.py

  4. Generate a complete codebase tutorial by running the main script:

    # Analyze a GitHub repository
python main.py --repo https://github.com/username/repo --include "*.py" "*.js" --exclude "tests/*" --max-size 50000

# Or, analyze a local directory
python main.py --dir /path/to/your/codebase --include "*.py" --exclude "*test*"

# Or, generate a tutorial in Chinese
python main.py --repo https://github.com/username/repo --language "Chinese"
    • --repo or --dir - Specify either a GitHub repo URL or a local directory path (required, mutually exclusive)
    • -n, --name - Project name (optional, derived from URL/directory if omitted)
    • -t, --token - GitHub token (or set GITHUB_TOKEN environment variable)
    • -o, --output - Output directory (default: ./output)
    • -i, --include - Files to include (e.g., "*.py" "*.js")
    • -e, --exclude - Files to exclude (e.g., "tests/*" "docs/*")
    • -s, --max-size - Maximum file size in bytes (default: 100KB)
    • --language - Language for the generated tutorial (default: "english")
    • --max-abstractions - Maximum number of abstractions to identify (default: 10)
    • --no-cache - Disable LLM response caching (default: caching enabled)

The application will crawl the repository, analyze the codebase structure, generate tutorial content in the specified language, and save the output in the specified directory (default: ./output).

🐳 Running with Docker

To run this project in a Docker container, you'll need to pass your API keys as environment variables.

  1. Build the Docker image

    docker build -t pocketflow-app .

  2. Run the container

    You'll need to provide your GEMINI_API_KEY for the LLM to function. If you're analyzing private GitHub repositories or want to avoid rate limits, also provide your GITHUB_TOKEN.

    Mount a local directory to /app/output inside the container to access the generated tutorials on your host machine.

    Example for analyzing a public GitHub repository:

    docker run -it --rm \
  -e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
  -v "$(pwd)/output_tutorials":/app/output \
  pocketflow-app --repo https://github.com/username/repo

    Example for analyzing a local directory:

    docker run -it --rm \
  -e GEMINI_API_KEY="YOUR_GEMINI_API_KEY_HERE" \
  -v "/path/to/your/local_codebase":/app/code_to_analyze \
  -v "$(pwd)/output_tutorials":/app/output \
  pocketflow-app --dir /app/code_to_analyze

💡 Development Tutorial


Pocket Flow Codebase Tutorial

PocketFlow-Tutorial-Codebase-Knowledge (The-Pocket/PocketFlow-Tutorial-Codebase-Knowledge)

Searching Database…

12.7K ·GitHub
PocketFlow-Tutorial-Codebase-Knowledge
Что это такое?Инструмент, который обходит репозиторий GitHub (или локальную папку), анализирует кодовую базу с помощью LLM, находит ключевые абстракции и то, как они взаимодействуют друг с другом, и превращает этот анализ в туториал для новичков с визуализациями.
Это библиотека, которую я подключаю в проект, или скрипт, который я запускаю?Это скрипт командной строки (main.py), который вы запускаете напрямую. Он построен на Pocket Flow, собственном фреймворке автора на 100 строк для LLM, который объединяет шаги агентов в цепочку.
Как создать туториал для репозитория?Клонируйте репозиторий, установите зависимости, укажите учетные данные LLM в utils/call_llm.py (или в файле .env), затем запустите основной скрипт с параметром --repo или --dir. Результат по умолчанию сохраняется в ./output.
Нужен ли мне ключ API, прежде чем я смогу этим пользоваться?Да, нужен ключ API для LLM. По умолчанию используется GEMINI_API_KEY из Google AI Studio для Gemini Pro 2.5, но можно сменить провайдера (например, задать LLM_PROVIDER=XAI) или подключиться к локальному серверу Ollama без ключа API.
Хорошо ли это работает с любой LLM?Нет. Авторы рекомендуют использовать самые новые модели с возможностью рассуждений (Claude 3.7 в режиме thinking, O1), так как более слабые модели плохо определяют ключевые абстракции в кодовой базе.
Кому это полезно?Разработчикам, которым нужно быстро разобраться в незнакомой кодовой базе, вместо того чтобы читать её построчно с нуля.
Можно ли анализировать мои приватные репозитории?Да, передайте токен GitHub через параметр --token или переменную окружения GITHUB_TOKEN, чтобы получить доступ к приватным репозиториям или обойти ограничения на количество запросов.
Можно ли запустить это в Docker вместо установки зависимостей Python на компьютер?Да, в проекте есть Dockerfile. Соберите образ, передайте GEMINI_API_KEY (и при необходимости GITHUB_TOKEN) как переменные окружения и подключите локальную папку к /app/output, чтобы получить готовый туториал.
Можно ли создать туториал на языке, отличном от английского?Да, флаг --language позволяет выбрать язык создаваемого туториала. По умолчанию используется английский.
Что такое Pocket Flow?Это минималистичный LLM-фреймворк автора на 100 строк, на котором построен агент для создания туториалов. Он спроектирован так, чтобы агенты могли создавать других агентов.
Есть ли примеры туториалов, которые можно посмотреть в первую очередь?Да, в README приведены ссылки на туториалы, созданные ИИ для популярных репозиториев: FastAPI, Flask, Requests, CrewAI, LangGraph и NumPy Core. Все они получены с помощью этого инструмента при обходе этих репозиториев.
What are similar projects?PocketFlow, Raven, ai-agent-book, DeepCode, ai-system-design, minimind, wikiskill, Prompt-Engineering-Guide
Which topics is it in?llm-framework, large-language-model, llm-agent, coding, llms, llm-agents, large-language-models, knowledge-base, documentation, tutorial, agent, education
Creator
The-Pocket
Size
11.6 MB
Stars
12.7K
Updated
CommitMay 31
Age
1y
Commits · 90 Days