Skip to content

chore: repo cleanup — badges, URLs, metadata, keywords#44

Merged
johnnichev merged 1 commit intomainfrom
chore/repo-cleanup-pass
Apr 7, 2026
Merged

chore: repo cleanup — badges, URLs, metadata, keywords#44
johnnichev merged 1 commit intomainfrom
chore/repo-cleanup-pass

Conversation

@johnnichev
Copy link
Copy Markdown
Owner

Summary

General cleanup pass across README, pyproject.toml, and GitHub repo metadata. Fixes one genuinely broken item (stale example count) and aligns the project's public identity across all three sources of truth (PyPI page, GitHub landing page, README).

What was broken

Example count was wrong. The README "Examples Gallery" badge said examples-76_scripts but the actual count in examples/ is 88 .py files. Caught via find examples -maxdepth 1 -name '*.py' | wc -l. This is the most common form of documentation drift — static numbers in badges are where stale info hides.

Homepage URL was inconsistent across three places:

Source Was Now
pyproject.toml Homepage https://nichevlabs.com https://selectools.dev
GitHub repo homepageUrl https://johnnichev.github.io/selectools https://selectools.dev
README docs badge linked to selectools.dev correctly (unchanged)

Three sources of truth, three different values. Someone clicking "Homepage" on the PyPI package page ended up at the parent company site instead of the project docs. Fixed.

What changed

README.md (+8 / -6)

Badge row reorganized and upgraded:

Before:
```markdown
PyPI version
Documentation
License: Apache 2.0
Python 3.9+
Evaluators
```

After:
```markdown
PyPI
Downloads
CI
Docs
Python
License
Evaluators
```

Per-badge rationale:

  • PyPI: Switched from `badge.fury.io` (unreliable, often 503s or stale) to `shields.io/pypi/v` (reads directly from PyPI API, updates in real time)
  • Downloads (new): PyPI downloads per month via pepy.tech — standard social-proof signal for a library
  • CI (new): GitHub Actions workflow badge — quality signal showing the test suite passes
  • Docs: Label changed from "GitHub Pages" → "selectools.dev" (the old label was technically still true but confusing post-domain migration)
  • Python: Static `python-3.9+` → dynamic `pyversions` badge that auto-updates from PyPI classifiers when the supported range changes in future releases
  • License: Unchanged in function, minor label/color cleanup
  • Evaluators: Kept (50 is still correct)
  • All cyan accents consolidated to the brand cyan `#06b6d4`

Stale count fixed:
```diff
-Examples Gallery
+Examples Gallery
```

`pyproject.toml` (+13 / -4)

Description tightened (268 → 207 chars):
```diff
-description = "Production-ready AI agents with tool calling, structured output, execution traces, and RAG. Provider-agnostic (OpenAI, Anthropic, Gemini, Ollama) with fallback chains, batch processing, tool policies, streaming, caching, and cost tracking."
+description = "Production-ready Python framework for AI agents with multi-agent graphs, hybrid RAG, guardrails, audit logging, 50 evaluators, and a visual builder. Supports OpenAI, Anthropic, Gemini, Ollama. By NichevLabs."
```

Keywords expanded and reformatted (16 → 23 keywords, now multi-line):

  • Added: `multi-agent`, `agent-framework`, `agents`, `ollama`, `guardrails`, `evals`, `evaluators`, `visual-builder`, `langchain-alternative`
  • Removed: None
  • These match what users actually search for on PyPI and align with the GitHub topic list

URLs restructured:
```diff
[project.urls]
-Homepage = "https://nichevlabs.com"
+Homepage = "https://selectools.dev"
+Documentation = "https://selectools.dev"
Repository = "https://github.com/johnnichev/selectools"
Issues = "https://github.com/johnnichev/selectools/issues"
-Documentation = "https://selectools.dev"
Changelog = "https://github.com/johnnichev/selectools/blob/main/CHANGELOG.md"
+Builder = "https://selectools.dev/builder/"
+Examples = "https://selectools.dev/examples/"
+"NichevLabs" = "https://nichevlabs.com"
```

  • `Homepage` is now the project site (was the parent company, which doesn't make sense as a package's home)
  • `Documentation` moved up to be right under Homepage (they point to the same place for this library, which is fine)
  • `Builder` and `Examples` added as direct links to the two killer features
  • NichevLabs attribution moved to a clearly-labeled separate link so it's preserved but doesn't masquerade as the project homepage

GitHub repo metadata (via `gh repo edit`, applied to origin directly)

Homepage URL fixed:

Topics canonicalized (19 → 18):

Removed Reason
`multi-agents` Plural dup of `multi-agent`
`multi-agents-orchestration` Plural dup of `multi-agent-orchestration`
`multi-agents-system` Plural dup, too specific
`langchain-alternatives` Plural dup of `langchain-alternative`
`apache-2-0-license` GitHub shows license in sidebar automatically
Added Reason
`multi-agent-orchestration` Canonical singular form
`tool-calling` Was in pyproject keywords but not GitHub topics
`agent-framework` High-traffic search term
`visual-builder` Genuine differentiator vs other frameworks
`evals` The eval framework is a differentiator

Final 18 topics: `ai-agents, ai-safety, anthropic, enterprise-ai, gemini, guardrails, llm, ollama, openai, python, rag, tool-calling, langchain-alternative, multi-agent, agent-framework, evals, multi-agent-orchestration, visual-builder`

All plural variants eliminated — GitHub topic search is exact-match, so plural dups fragment searches and make the repo discoverable under more terms but less consistently. The canonical singular forms (matching LangChain/CrewAI/AutoGen conventions) are the right home.

Verification

  • Pre-commit hooks pass 14/14 (including `Check TOML syntax` and `Trim trailing whitespace`)
  • `pyproject.toml` bracket balance check clean (42/42, 3/3)
  • Description length: 268 → 207 chars
  • `gh repo view` confirms new homepage and topic list applied on origin
  • All cyan badge colors consolidated to `#06b6d4` brand cyan
  • No broken or stale `johnnichev.github.io` references anywhere in the public surface

What's NOT in this PR

  • No content changes to `docs/*.md` — audit found no stale external links (PR feat: animation/delight pass + selectools.dev custom domain #40 already cleaned those up)
  • No CHANGELOG entry — this is repo hygiene, not a user-facing code change
  • No version bump
  • No GitHub-side actions beyond `gh repo edit` (no release retagging, no PyPI re-upload)

The next release will naturally pick up the new `pyproject.toml` metadata on PyPI without any extra steps.

General cleanup pass across README, pyproject.toml, and GitHub repo
metadata. Fixes one genuinely broken item (stale example count) and
aligns the project's public identity across all sources of truth.

README badges (top of file):
  - Replaced badge.fury.io/py/selectools.svg with shields.io/pypi/v,
    which reads directly from the PyPI API and updates in real time
    (badge.fury.io has been unreliable for years, frequently serving
    503s or stale data)
  - Docs label changed from "GitHub Pages" to "selectools.dev" — the
    old label was technically still accurate but confusing post-domain
    migration
  - Python badge switched from static "python-3.9+" to dynamic
    shields.io/pypi/pyversions/selectools, which auto-updates when the
    supported Python range changes in future releases
  - Added CI status badge pointing at .github/workflows/ci.yml
  - Added PyPI downloads/month badge from pepy.tech
  - All cyan-accented badges now use consistent #06b6d4 (brand cyan)
  - Evaluators badge kept (50 is still accurate)

README stale count fix:
  - "Examples Gallery" badge said examples-76_scripts but there are
    actually 88 .py files in examples/. Updated to 88_scripts.
    Caught via `find examples -maxdepth 1 -name '*.py' | wc -l`.

pyproject.toml:
  - Homepage URL fixed: was https://nichevlabs.com (parent company),
    now https://selectools.dev (the actual project home). This is what
    PyPI displays as the "Homepage" link on the package page, so the
    old value sent users to the wrong place.
  - Description tightened from 268 chars to 207 chars. Same
    information density, less run-on. Aligns with the cleaner GitHub
    repo description.
  - Keywords expanded and reformatted: added multi-agent,
    agent-framework, agent, agents, guardrails, evals, evaluators,
    visual-builder, ollama, langchain-alternative. These match what
    users actually search for on PyPI.
  - Added Builder and Examples entries to [project.urls], plus a
    NichevLabs attribution link. PyPI renders these as clickable
    sidebar links on the package page.

GitHub repo metadata (via `gh repo edit`, applied separately):
  - homepageUrl fixed: was johnnichev.github.io/selectools (pre-domain
    migration URL), now https://selectools.dev
  - Deduplicated redundant plural topics: removed multi-agents,
    multi-agents-orchestration, multi-agents-system, langchain-
    alternatives (keeping the canonical singular forms which match
    LangChain/CrewAI/AutoGen conventions)
  - Removed apache-2-0-license topic (GitHub shows license
    automatically in the sidebar; topics aren't the right channel)
  - Added tool-calling, agent-framework, visual-builder, evals —
    high-traffic search terms that also differentiate selectools from
    other agent frameworks
  - Final topic count: 18 (down from 19, but canonicalized)

What's NOT in this PR:
  - No content changes to docs/*.md (no stale external links found)
  - No CHANGELOG entry since this is repo hygiene, not a user-facing
    code change
  - No version bump
@johnnichev johnnichev merged commit ba1cd67 into main Apr 7, 2026
9 checks passed
@johnnichev johnnichev deleted the chore/repo-cleanup-pass branch April 8, 2026 03:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant