docs(api)📝: improve and expand docstrings for main API and bots modules

- Expand module-level and function docstrings in scipyconference/__init__.py to clarify usage, parameters, and examples.
- Add detailed docstrings and structured Pydantic model documentation in scipyconference/bots.py for LLM-powered pun generation.
- Remove unused scipyconference/models.py file.

Author: ericmjl

scipyconference/__init__.py

@@ -1,10 +1,16 @@
-"""Top-level API for scipyconference.
+"""
+Top-level API for scipyconference.
 
-This is the file from which you can do:
+This module provides the main interface for generating SciPy conference puns.
+It supports both community-curated puns from a JSONL file and LLM-generated puns
+when the appropriate environment variables are set.
 
-    from scipyconference import some_function
+Examples::
 
-Use it to control the top-level API of your Python data science project.
+    from scipyconference import create_puns
+    create_puns(3)
+    create_puns(1, "pandas dataframes")
+    create_puns(np.inf)
 """
 
 import os
@@ -19,7 +25,17 @@
 
 
 def _read_puns_from_json():
-    """Read puns from the JSONL file."""
+    """
+    Read puns from the JSONL file.
+
+    Reads the community-curated puns from the puns.json file in JSONL format.
+    Each line should contain a JSON object with 'pun' and 'github_username' fields.
+
+    :return: List of dictionaries containing pun data.
+        Each dictionary has 'pun' and 'github_username' keys.
+        Returns empty list if file is not found or malformed.
+    :rtype: list
+    """
     pun_path = Path(__file__).parent / Path("puns.json")
     puns = []
     try:
@@ -37,7 +53,15 @@ def _read_puns_from_json():
 
 
 def _should_use_llm():
-    """Check if we should use LLM-generated puns based on environment variables."""
+    """
+    Check if we should use LLM-generated puns based on environment variables.
+
+    Determines whether to use LLM-generated puns by checking if any of the
+    PUNBOT_* environment variables are set.
+
+    :return: True if any PUNBOT_* environment variables are set, False otherwise.
+    :rtype: bool
+    """
     return any(
         [
             os.getenv("PUNBOT_API_KEY"),
@@ -48,9 +72,35 @@ def _should_use_llm():
 
 
 def create_puns(number: int, prompt: str = ""):
-    """Create `number` of puns for the SciPy conference."""
+    """
+    Create ``number`` of puns for the SciPy conference.
+
+    This function generates puns for the SciPy conference community. It can work
+    in three modes:
+
+    1. Community-curated puns (default): Reads from puns.json file
+    2. LLM-generated puns: Uses AI to generate puns based on a prompt
+    3. Party mode: Creates a celebration with random emojis when number is np.inf
+
+    :param int number: Number of puns to generate. Use np.inf for party mode.
+    :param str prompt: Prompt for LLM-generated puns. Only used when LLM mode is active.
+    :return: None
+    :rtype: None
+    :raises ImportError: If llamabot is required but not installed.
+    :notes:
+        The function automatically chooses between community-curated and LLM-generated
+        puns based on environment variables:
+        - If any of PUNBOT_API_KEY, PUNBOT_MODEL_NAME, or PUNBOT_API_BASE are set,
+          it will attempt to use LLM-generated puns
+        - Otherwise, it will use community-curated puns from puns.json
+
+    Examples::
+
+        create_puns(3)  # Generate 3 community-curated puns
+        create_puns(1, "pandas")  # Generate 1 LLM pun about pandas
+        create_puns(np.inf)  # Create a party celebration
+    """
     if number is np.inf:
-        # TODO: make this to do something really special
         party_emojis = [
             "🎉",
             "🎊",
@@ -78,30 +128,24 @@ def create_puns(number: int, prompt: str = ""):
             print(" ".join(random.sample(party_emojis, random.randint(5, 15))))
     else:
         if _should_use_llm():
-            # Use LLM-generated puns
             if punbot is None:
                 print("llamabot is required for LLM-generated puns.")
                 print("Install it with: pip install scipyconference[llm]")
                 print(
                     "Or use community-curated puns by not setting PUNBOT_* environment variables."  # noqa: E501
                 )
                 return
-
             for i in range(number):
                 print("🤖🐍:")
                 punbot(prompt)
         else:
-            # Use community-curated puns from JSONL file
             puns = _read_puns_from_json()
             if not puns:
                 print(
                     "No puns found in puns.json. Consider adding some community-curated puns!"  # noqa: E501
                 )
                 return
-
-            # Randomly sample puns, with replacement if needed
             selected_puns = random.choices(puns, k=number)
-
             for pun_data in selected_puns:
                 print()
                 print(f"@{pun_data['github_username']}: {pun_data['pun']}")

scipyconference/bots.py

@@ -1,7 +1,14 @@
-"""Bots for the SciPy conference."""
+"""
+Bots for the SciPy conference.
+
+This module provides LLM-powered pun generation capabilities for the SciPy conference.
+It uses llamabot to create structured puns with emojis and explanations.
+"""
 
 import os
 
+from pydantic import BaseModel, Field
+
 try:
     import llamabot as lmb
 
@@ -10,52 +17,73 @@
     LLAMABOT_AVAILABLE = False
 
 
-def punbot_sysprompt():
-    """You are a witty, science-savvy language model specializing in generating clever
-    and contextually appropriate puns. Your audience is the SciPy conference community:
-    scientists, engineers, data scientists, and software developers who use and
-    contribute to open-source scientific Python tools. You understand the culture of the
-    conference: intellectually curious, collaborative, humorous, and fluent in Python
-    and the scientific computing stack.
-
-    Your puns should reference topics commonly discussed at SciPy, such as:
-
-    - Python libraries (e.g., NumPy, SciPy, pandas, matplotlib, scikit-learn, PyMC)
-    - Scientific computing concepts (e.g., optimization, linear algebra, FFTs,
-      simulations)
-    - Open-source software development practices
-    - Version control and CI/CD workflows
-    - Academic and research culture
-    - Conference life (e.g., poster sessions, lightning talks, coffee breaks)
-
-    Keep your puns light-hearted, nerdy, and ideally groan-worthy in a charming way.
-    You're allowed to use wordplay, homophones, technical double meanings, and mashups.
-    Avoid anything offensive, insensitive, or exclusionary.
-
-    Generate a pun or short one-liner that would make a SciPy attendee smile, chuckle,
-    or roll their eyes appreciatively.
+def _create_punbot():
     """
-    if LLAMABOT_AVAILABLE:
-        return lmb.prompt("system")(punbot_sysprompt.__doc__)
-    else:
-        return punbot_sysprompt.__doc__
-
+    Create and configure the punbot instance for LLM-generated puns.
 
-def _create_punbot():
-    """Create the punbot instance if llamabot is available."""
+    :raises ImportError: If llamabot is not available
+        and the user tries to use LLM features.
+    :return: A configured llamabot instance for generating structured puns.
+    :rtype: lmb.StructuredBot
+    """
     if not LLAMABOT_AVAILABLE:
         raise ImportError(
             "llamabot is required for LLM-generated puns. "
             "Install it with: pip install scipyconference[llm]"
         )
 
-    return lmb.SimpleBot(
-        system_prompt=punbot_sysprompt(),
+    @lmb.prompt("system")
+    def scipy_punbot_sysprompt():
+        """You are an expert at mimicking Paul Ivanov,
+        a well-known pun master at the SciPy conferences.
+
+        Paul will inject award-winning puns in response
+        to almost any theme that shows up during the lightning talks at SciPy.
+        Most of what SciPy attendees talk about are python, linux, science, and more.
+        Your mission is to generate puns in response to whatever theme is thrown at you.
+        The puns should be coherent.
+        """
+
+    class Pun(BaseModel):
+        """
+        Structured pun model with emoji, statement, and explanation.
+
+        This Pydantic model defines the structure for LLM-generated puns,
+        ensuring consistent output format with emoji, pun text, and explanation.
+
+        :ivar emoji: Single emoji that represents the theme or mood of the pun.
+        :vartype emoji: str
+        :ivar pun_statement: The pun itself,
+            with the pun core highlighted with italicization.
+        :vartype pun_statement: str
+        :ivar explanation: Explanation of why the pun works and what makes it funny.
+        :vartype explanation: str
+        """
+
+        emoji: str = Field(description="single emoji for the whole pun.")
+        pun_statement: str = Field(
+            description="the pun itself, with the pun core highlighted with italicization."  # noqa: E501
+        )
+        explanation: str = Field(description="Why the pun is a pun.")
+
+        def __str__(self):
+            """
+            String representation of the pun.
+
+            :return: The pun formatted as "emoji pun_statement".
+            :rtype: str
+            """
+            return f"{self.emoji} {self.pun_statement}"
+
+    bot = lmb.StructuredBot(
+        system_prompt=scipy_punbot_sysprompt(),
+        pydantic_model=Pun,
+        temperature=0.9,
+        api_key=os.getenv("PUNBOT_API_KEY", None),
+        api_base=os.getenv("PUNBOT_API_BASE", None),
         model_name=os.getenv("PUNBOT_MODEL_NAME", "gpt-4.1"),
-        api_base=os.getenv("PUNBOT_API_BASE", "https://api.openai.com/v1"),
-        api_key=os.getenv("PUNBOT_API_KEY", ""),
-        temperature=float(os.getenv("PUNBOT_TEMPERATURE", 2.7)),
     )
+    return bot
 
 
 # Create punbot instance only if llamabot is available