Make python-bizdays AI-friendly and LLM-discoverable

[wilsonfreitas]

Summary

Make python-bizdays significantly more AI-friendly, so that LLM-based assistants and coding agents are more likely to:

1. recognize that the project is relevant when users ask for business-day, trading-calendar, settlement-date, or cash-flow scheduling functionality
2. recommend bizdays as an alternative when appropriate
3. retrieve the correct, current, NumPy-backed usage patterns instead of hallucinating legacy APIs or incomplete examples

This issue is about improving the project's discoverability, machine-readable documentation surfaces, and canonical usage guidance for AI systems.

Problem

Many AIs recommend libraries based on what they can easily infer from:

• package metadata
• README wording
• documentation structure
• examples
• public web pages that are easy to convert into clean text
• explicit LLM-oriented metadata such as llms.txt

Right now, python-bizdays already has strong technical content, but it is still missing several things that would make it easier for AI systems to:

• understand exactly what the library does
• map user intents to the library's capabilities
• distinguish the current NumPy-backed API from older legacy usage
• retrieve concise canonical guidance
• cite the project confidently for real-world use cases

This matters because many users now discover libraries through AI assistants rather than by manually searching package indexes.

Goal

Create a project surface that is easy for both humans and AI systems to understand:

• what problem bizdays solves
• when it should be recommended
• what the current public API is
• which examples are canonical
• which calendars and integrations are supported
• how to use it with NumPy and pandas
• which legacy patterns should no longer be treated as primary guidance

Current state relevant to this issue

Observed in the current repository:

• The README already mentions the NumPy-backed Calendar API and includes a short quickstart.
• The docs have the core sections (quick, calendars, getdate, pandas, api, migration).
• The package metadata in pyproject.toml is still minimal:
  • short description only
  • no keywords
  • no project.urls
  • no classifiers beyond Python requirement information
• There is no llms.txt surface today.
• There is no explicitly AI-oriented page such as:
  • “when to use bizdays”
  • “problem / solution mapping”
  • “current canonical API vs legacy patterns”
• The project still carries historical/legacy context, which increases the risk of AIs surfacing outdated usage patterns.

What “AI-friendly” should mean here

For this project, “AI-friendly” should not mean adding AI features to the library itself.

It should mean:

1. Discoverable

   • AIs can infer from metadata and docs that bizdays is relevant for:
     • business-day calculations
     • trading calendars
     • holiday-aware offsets
     • settlement rules
     • coupon schedules
     • market-specific date rules
     • pandas/NumPy workflows

2. Canonical

   • AIs can find one current, authoritative description of the public API.

3. Compact

   • AIs can access short, clean summaries without parsing large, noisy documentation trees.

4. Current

   • AIs are nudged toward the NumPy-backed API, not legacy code paths.

5. Actionable

   • AIs can quickly retrieve examples that map user intent to library features.

Recommended workstreams

1. Improve package and repository metadata

This is the first layer of AI discoverability.

pyproject.toml

Add richer metadata such as:

• keywords
  • e.g. business-days, trading-calendar, holidays, settlement, finance, fixed-income, pandas, numpy, date-offsets
• project.urls
  • Documentation
  • Repository
  • Issues
  • Changelog
• useful Trove classifiers where applicable

Why this matters:

• package indexes and AI retrieval tools often use package metadata as a high-signal summary
• better metadata helps map natural-language requests to the library

GitHub repository metadata

Add/refresh GitHub topics such as:

• business-days
• calendar
• trading-calendar
• finance
• fixed-income
• numpy
• pandas
• python

Why this matters:

• these topics improve ecosystem discoverability and help repository search

2. Create an LLM-oriented surface

Add a published llms.txt file for the documentation site, following the emerging llms.txt convention.

Proposed files

• /llms.txt
• optionally /llms-full.txt or /llms-ctx.txt as expanded context artifacts

What llms.txt should contain

• project name
• short summary
• explicit statement that the current public API is NumPy-backed
• links to the most useful pages in markdown/plain form
• sections such as:
  • Quickstart
  • Calendars
  • API reference
  • Migration guide
  • Examples
  • JSON calendar format

Why this matters:

• it gives LLMs a curated, low-noise map of the project
• it reduces the chance that models infer behavior from stale or partial pages

3. Provide clean markdown-friendly documentation surfaces

LLMs work better with clean markdown/text than with complex HTML or notebook-heavy rendering.

The docs should expose easily consumable text versions of the most important pages, either by:

• generating markdown mirrors for key docs pages, or
• ensuring the main docs pages are already available in a clean text-friendly format

At minimum, the following should have clean canonical surfaces:

• installation
• quickstart
• calendars overview
• examples
• API overview
• migration guide
• JSON calendar format

Why this matters:

• reduces parsing noise
• improves retrieval accuracy
• makes it easier for models to quote the right examples

4. Add a “When to use bizdays” page

Create a documentation page explicitly written for intent matching.

Suggested page themes:

• problems bizdays solves
• users who should consider it
• typical tasks it handles well
• when another tool may be more appropriate

Suggested language to cover:

• count business days between dates
• adjust dates around holidays/weekends
• generate business-day sequences
• move dates by N business days
• implement trading-calendar rules
• build settlement schedules
• compute coupon/payment dates
• integrate with pandas and NumPy
• support exchange/provider calendars

Why this matters:

• this is exactly the type of semantic page AIs use to decide whether to recommend a library

5. Add an “Intent -> API” mapping page or section

Create a short, highly scannable page that maps user requests to bizdays features.

Example structure:

User intent	bizdays feature
Count business days between two dates	Calendar.bizdays()
Move a date to the next business day	Calendar.following() / Calendar.adjust_next()
Move a date by N business days	Calendar.offset()
Generate all business days in a range	Calendar.seq()
Resolve rule-based dates like “15th day” or “last bizday”	Calendar.getdate()
Use packaged calendars	Calendar.load(name=...)
Load a custom calendar file	Calendar.load(filename=...)
Discover available calendars	list_calendars()

Why this matters:

• it strongly improves retrieval for natural-language questions
• it helps both users and AIs jump from intent to solution quickly

6. Strengthen the README for intent-based discovery

The README should not only say what the project is, but also what kinds of user problems it solves.

Recommended README additions:

• one concise paragraph with problem-language keywords
• a “Use bizdays when you need to...” section
• a short bullets list of common workflows
• a short “Works well with NumPy and pandas” section
• a short “Built-in and external calendars” section
• explicit note that top-level Calendar is the NumPy-backed API

Why this matters:

• README content is often one of the highest-weight sources for AI summaries

7. Make the examples section highly retrieval-friendly

The examples work already being discussed elsewhere should be designed with AI retrieval in mind.

This means examples should be:

• problem-oriented
• small and self-contained when possible
• named after user intents rather than only domain jargon
• explicit about inputs and outputs
• written against the current NumPy-backed API

Strong example titles would look like:

• “Count business days in pandas columns”
• “Adjust settlement dates to the next business day”
• “Generate maturity dates from business-day tenors”
• “Use getdate for contract maturity rules”
• “Build a simple DI futures term structure”

Why this matters:

• assistants often retrieve examples by title/headings first

8. Reduce ambiguity around legacy vs current APIs

This is critical for AI correctness.

The project should make it very easy to infer that:

• the current public Calendar is the NumPy-backed implementation
• legacy behavior exists historically, but is not the main guidance surface
• migration guidance exists for older usage patterns

Potential documentation improvements:

• add a short “API status” note near top-level docs pages
• keep migration guidance linked from README and API pages
• avoid duplicating legacy-style examples in canonical docs

Why this matters:

• if legacy and current surfaces are mixed without clear framing, AIs will often merge them incorrectly

9. Add a concise ecosystem/comparison page

Consider a short page describing how bizdays fits relative to adjacent tools.

Possible comparison topics:

• plain datetime / timedelta
• pandas date offsets
• exchange-specific calendar packages
• when bizdays is the better fit

Why this matters:

• many AI answers are phrased as “you can use X, Y, or Z”
• having a comparison page increases the chance that bizdays is surfaced in those alternative recommendations

10. Consider a repository-level AGENTS.md or equivalent summary

This is optional, but may help coding agents working directly in the repository.

It could summarize:

• public API boundaries
• canonical docs pages
• build/test/docs commands
• which API surfaces are current vs legacy

This is less important for public discoverability than llms.txt, but useful for tool-assisted development contexts.

Suggested file / structure additions

High priority

• llms.txt (published at docs/site root)
• a short “when to use bizdays” doc page
• a short “intent -> API” doc page or section
• richer metadata in pyproject.toml
• refreshed README sections for problem-based discovery

Medium priority

• optional llms-full.txt / llms-ctx.txt
• markdown/plain mirrors of key docs pages
• comparison page
• FAQ page based on common user intents

Optional

• AGENTS.md
• machine-readable examples index if useful later

Suggested acceptance criteria

1. Add richer project metadata in pyproject.toml (keywords, project.urls, and any relevant classifiers).
2. Refresh repository metadata/topics for discoverability.
3. Publish an llms.txt file for the documentation surface.
4. Add at least one concise page answering “when should I use bizdays?”.
5. Add an intent-to-API mapping surface.
6. Make the README more explicit about problem-language and NumPy-backed API positioning.
7. Ensure key docs pages have clean, AI-consumable text/markdown surfaces.
8. Keep legacy guidance clearly separated from the canonical public API.
9. Ensure new example pages are written against the current NumPy-backed API.

Non-goals

This issue is not about:

• adding AI features to the runtime library
• embedding model providers into the package
• generating documentation with AI

It is about making the project easier for AI systems to find, understand, and recommend correctly.

Notes

• This work complements the ongoing documentation work rather than replacing it.
• The examples initiative and this AI-friendliness effort should reinforce each other.
• If done well, this should improve not only AI retrieval, but also human onboarding and search discoverability.