fix: docstrings (#177)

* fix: reformat docstrings

* fix: remove extra params from docstring

* fix: remove cli and docs from linter

Author: jakelorocco

.pre-commit-config.yaml

@@ -11,7 +11,7 @@ repos:
       - id: ruff
         name: "Ruff linter"
         args: [--exit-non-zero-on-fix, --fix, --config=pyproject.toml]
-        files: '^(mellea|tests|cli|docs).*\.(py|ipynb)$'
+        files: '^(mellea|tests).*\.(py|ipynb)$'
 
   - repo: local
     hooks:

cli/alora/upload.py

@@ -5,8 +5,7 @@
 
 
 def upload_model(weight_path: str, model_name: str, private: bool = True):
-    """
-    Upload a trained adapter (LoRA/aLoRA) to Hugging Face Hub.
+    """Upload a trained adapter (LoRA/aLoRA) to Hugging Face Hub.
 
     Args:
         weight_path (str): Directory containing adapter weights (from save_pretrained).

cli/m.py

@@ -12,7 +12,7 @@
 # Add a default callback for handling the default cli description.
 @cli.callback()
 def callback() -> None:
-    """Perform M Tasks"""
+    """Perform M Tasks."""
 
 
 # Typer assumes that all commands are in the same file/module.

docs/examples/best_of_n/prm.py

@@ -1,4 +1,4 @@
-"""Example of Using Best of N with PRMs"""
+"""Example of Using Best of N with PRMs."""
 
 from docs.examples.helper import w
 from mellea import start_session

docs/examples/generative_slots/generative_slots.py

@@ -9,8 +9,7 @@ def classify_sentiment(text: str) -> Literal["positive", "negative"]: ...
 
 @generative
 def generate_summary(text: str) -> str:
-    """
-    This is a function that takes in a string and generates a summary for the string.
+    """This is a function that takes in a string and generates a summary for the string.
     Keep your summary succinct and under 20 words.
     """
 

docs/examples/information_extraction/101_with_gen_slots.py

@@ -8,9 +8,7 @@
 
 @generative
 def extract_all_person_names(doc: str) -> list[str]:
-    """
-    Given a document, extract all person names. Return these names as list of strings.
-    """
+    """Given a document, extract all person names. Return these names as list of strings."""
 
 
 # ref: https://www.nytimes.com/2012/05/20/world/world-leaders-at-us-meeting-urge-growth-not-austerity.html

docs/examples/mini_researcher/researcher.py

@@ -19,20 +19,20 @@
 
 @cache
 def get_session():
-    """get M session (change model here)"""
+    """Get M session (change model here)."""
     return MelleaSession(backend=OllamaModelBackend(model_ids.IBM_GRANITE_3_3_8B))
 
 
 @cache
 def get_guardian_session():
-    """get M session for the guardian model"""
+    """Get M session for the guardian model."""
     return MelleaSession(
         backend=OllamaModelBackend(model_ids.IBM_GRANITE_GUARDIAN_3_0_2B)
     )
 
 
 def is_a_true_subset_of_b(a: list[str], b: list[str]) -> bool:
-    """check if a is true subset of b."""
+    """Check if a is true subset of b."""
     all_in = True
     for e in a:
         if e not in b:
@@ -42,7 +42,7 @@ def is_a_true_subset_of_b(a: list[str], b: list[str]) -> bool:
 
 
 def create_check_word_count(max_words: int) -> Callable[[str], bool]:
-    """generate a maximum-word-count validation function."""
+    """Generate a maximum-word-count validation function."""
 
     def cc(s: str):
         return len(s.split()) <= max_words
@@ -56,7 +56,7 @@ def cc(s: str):
 
 
 def step_is_input_safe(guardian_session: MelleaSession, docs: list[str]) -> bool:
-    """check if the list of docs has no harm."""
+    """Check if the list of docs has no harm."""
     is_safe = True
     for i_doc, doc in enumerate(docs):
         print(f"\nChecking Doc {i_doc + 1}/{len(docs)}", end="...")
@@ -73,7 +73,7 @@ def step_is_input_safe(guardian_session: MelleaSession, docs: list[str]) -> bool
 def step_summarize_docs(
     s: MelleaSession, docs: list[str], user_args: dict
 ) -> list[str]:
-    """generate a task-specific document summary for each doc."""
+    """Generate a task-specific document summary for each doc."""
     summaries = []
     for i_doc, doc in enumerate(docs):  # type: ignore
         print(f"\nSummarizing doc {i_doc + 1}/{len(docs)}", end="...")
@@ -91,7 +91,6 @@ def step_generate_outline(
     s: MelleaSession, user_args: dict, context: list[RAGDocument]
 ) -> list[str]:
     """Generate a report outline using constraint decoding (formatted output)."""
-
     print("\n Generating outline", end="...")
 
     class SectionTitles(BaseModel):
@@ -165,7 +164,6 @@ def step_write_full_report(
     outline: list[str],
 ) -> str:
     """Merge summaries and outline into a single report."""
-
     print("\nWriting full report", end="...")
 
     ## Define Requirements

docs/examples/notebooks/mcp_example.ipynb

@@ -126,7 +126,7 @@
     "\n",
     "@mcp.resource(\"greeting://{name}\")\n",
     "def get_greeting(name: str) -> str:\n",
-    "    \"\"\"Get a personalized greeting\"\"\"\n",
+    "    \"\"\"Get a personalized greeting.\"\"\"\n",
     "    return f\"Hello, {name}!\""
    ]
   }

docs/examples/safety.py/guardian.py

@@ -1,4 +1,4 @@
-"""Example of using the Guardian Requirement"""
+"""Example of using the Guardian Requirement."""
 
 from mellea import MelleaSession
 from mellea.backends import model_ids

docs/examples/tutorial/mcp_example.py

@@ -1,4 +1,4 @@
-"""Example of an MCP server
+"""Example of an MCP server.
 
 You need to install the mcp package:
 uv pip install "mcp[cli]"
@@ -50,5 +50,5 @@ def write_a_poem(word_limit: int) -> str:
 
 @mcp.resource("greeting://{name}")
 def get_greeting(name: str) -> str:
-    """Get a personalized greeting"""
+    """Get a personalized greeting."""
     return f"Hello, {name}!"