fetch-llm-apps

name	fetch-llm-apps
description	Workflow for updating the popular LLM applications pool (section/x_llm_apps.md) using fetch_llm_apps.py. Covers full refresh, alternate exports, topic tuning, and common pitfalls. USE FOR: Refreshing the ranked GitHub applications list linked from applications.md. DO NOT USE FOR: Hand-curating application entries inside applications.md or adding GitHub star badges to the generated file.

Overview

The pool file section/x_llm_apps.md is a generated ranked list of GitHub repositories related to LLM apps, agents, chat UIs, workflow builders, and similar application-layer projects.

It is generated by code/fetch_llm_apps.py using GitHub topic search, deduplicated across multiple topics, and sorted by GitHub star count descending.

The section #### Popular LLM Applications (GitHub Stars >= 1000) in section/applications.md links to this generated file with a one-line description only. Do not paste generated entries directly into applications.md.

---

Script Reference

Script: code/fetch_llm_apps.py
Python env: .venv\Scripts\python.exe

Key CLI Arguments

Argument	Default	Purpose
--output	section/x_llm_apps.md	Output file path. Extension controls format: .md, .json, .csv
--min-stars	1000	Minimum GitHub star threshold
--topics	curated list	GitHub topics to query and merge
--token	GITHUB_TOKEN env var	GitHub PAT for higher rate limits
--show	30	Number of repos printed to console
--timeout	20	Per-request timeout in seconds
--max-retries	4	Max retries per request
--backoff	1.0	Initial retry backoff
--sleep	1.0	Delay between successful page requests
--include-archived	off	Include archived repositories
--append	off	Merge new results with an existing output file, then re-sort by stars

---

Workflow

1. Full refresh of the markdown pool

Use this for the normal update path.

.venv\Scripts\python.exe code/fetch_llm_apps.py

• Rewrites section/x_llm_apps.md.
• Uses --min-stars 1000 by default to match the section title.
• Excludes archived repos unless --include-archived is passed.
• Writes compact numbered entries instead of badge-heavy markdown.

2. Authenticated refresh to avoid GitHub API limits

.venv\Scripts\python.exe code/fetch_llm_apps.py --token $env:GITHUB_TOKEN

Use a GitHub PAT when doing a full refresh across many topics. Unauthenticated search is heavily rate-limited.

3. Generate a stricter ranking

.venv\Scripts\python.exe code/fetch_llm_apps.py --min-stars 2000

Use this when you want a tighter list. If you change the threshold materially, update the descriptive text in section/applications.md so the label stays truthful.

4. Export raw data for review

.venv\Scripts\python.exe code/fetch_llm_apps.py --output files/x_llm_apps.json
.venv\Scripts\python.exe code/fetch_llm_apps.py --output files/x_llm_apps.csv

Use JSON or CSV when you want to inspect or post-process the ranked repo pool before regenerating markdown.

5. Tune the topic set

.venv\Scripts\python.exe code/fetch_llm_apps.py --topics llm agent rag chatbot ai-workflow

• Topics are GitHub repository topics, not free-text queries.
• Results are deduplicated by full_name after all topic passes complete.
• If the topic set changes substantially, regenerate the markdown pool rather than editing it by hand.

6. Topic-specific doc update

If the output is intentionally narrowed to a subset such as gemini claude azure-openai copilot assistant, keep the ranked entries as generated, then update the document metadata and the linking description in section/applications.md to reflect the narrowed scope.

7. Add topics without discarding the current pool

.venv\Scripts\python.exe code/fetch_llm_apps.py `
	--append `
	--topics llm agent rag chatbot ai-workflow

--append parses the existing compact entries, merges newly fetched repositories by full_name, and rewrites the file sorted by star count. Use it when expanding coverage; use the normal full refresh when the default topic set changes substantially.

---

Output Format

Each entry in section/x_llm_apps.md follows this compact format:

1. [owner/repo](https://github.com/owner/repo): Short GitHub description. [Mon YYYY] (⭐ 12,345)

• Entries are sorted by GitHub stars descending.
• The date is the repository creation month, formatted as [Mon YYYY].
• The star count is static text in parentheses using the star symbol.
• Do not append realtime shields or badges in this generated file.

The file header includes:

• UTC generated timestamp
• GitHub Search API source note
• searched topic list
• total repository count

---

Common Pitfalls

1. Using the wrong output target: The generated ranking belongs in section/x_llm_apps.md, not inline inside section/applications.md.

2. Adding GitHub star badges: This file intentionally uses static text like (⭐ 12,345). Do not run add_github_stars.py on it.

3. Forgetting the star threshold contract: The linked section title says ≥1000. If you generate with a different threshold, either restore 1000 or update the section label and description.

4. Unauthenticated rate limits: Full runs over many topics can stall or fail without a token. Prefer GITHUB_TOKEN for routine refreshes.

5. Assuming GitHub topics are comprehensive: Some strong repos do not declare useful topics and may be missed. Expand --topics or curate separately if coverage is insufficient.

6. Archived repos polluting the ranking: Archived repos are excluded by default. Only include them deliberately.

7. Hand-editing generated entries: Manual changes will be lost on the next run. Adjust the script inputs or post-process separately instead.