Merge remote-tracking branch 'origin/main' into tests-isolation

Author: avinash2692

.github/workflows/quality.yml

@@ -0,0 +1,39 @@
+name: Verify Code Quality
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.event.pull_request.number || github.ref_name }}
+    cancel-in-progress: true
+
+jobs:
+  quality:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12'] # Need to add 3.13 once we resolve outlines issues.
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv and set the python version
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+      - name: pre-commit cache key
+        run: echo "PY=$(python -VV | sha256sum | cut -d' ' -f1)" >> "$GITHUB_ENV"
+      - uses: actions/cache@v4
+        with:
+          path: ~/.cache/pre-commit
+          key: pre-commit|${{ env.PY }}|${{ hashFiles('.pre-commit-config.yaml') }}
+      - name: Install dependencies
+        run: uv sync --frozen --all-extras
+      - name: Check style and run tests
+        run: pre-commit run --all-files
+      - name: Send failure message
+        if: failure()  # This step will only run if a previous step failed
+        run: echo "The quality verification failed. Please run precommit "

README.md

@@ -47,12 +47,30 @@ You can get started with a local install, or by using Colab notebooks.
 
 <img src="https://github.com/generative-computing/mellea/raw/main/docs/GetStarted_py.png" style="max-width:800px">
 
-Install with pip:
+Install with [uv](https://docs.astral.sh/uv/getting-started/installation/):
 
 ```bash
 uv pip install mellea
 ```
 
+Install with pip:
+
+```bash
+pip install mellea
+```
+
+> [!NOTE]
+> `mellea` comes with some additional packages as defined in our `pyproject.toml`. I you would like to install all the extra optional dependencies, please run the following commands:
+>
+> ```bash
+> uv pip install mellea[hf] # for Huggingface extras and Alora capabilities.
+> uv pip install mellea[watsonx] # for watsonx backend
+> uv pip install mellea[docling] # for docling
+> uv pip install mellea[all] # for all the optional dependencies
+> ```
+>
+> You can also install all the optional dependencies with `uv sync --all-extras`
+
 > [!NOTE]
 > If running on an Intel mac, you may get errors related to torch/torchvision versions. Conda maintains updated versions of these packages. You will need to create a conda environment and run `conda install 'torchvision>=0.22.0'` (this should also install pytorch and torchvision-extra). Then, you should be able to run `uv pip install mellea`. To run the examples, you will need to use `python <filename>` inside the conda environment instead of `uv run --with mellea <filename>`.
 
@@ -110,7 +128,19 @@ uv venv .venv && source .venv/bin/activate
 Use `uv pip` to install from source with the editable flag:
 
 ```bash
-uv pip install -e .
+uv pip install -e .[all]
+```
+
+If you are planning to contribute to the repo, it would be good to have all the development requirements installed:
+
+```bash
+uv pip install .[all] --group dev --group notebook --group docs
+```
+
+or 
+
+```bash
+uv sync --all-extras --all-groups
 ```
 
 Ensure that you install the precommit hooks:

docs/dev/constrained_decoding.md

@@ -10,7 +10,7 @@ The `m` framework currently uses the `format` argument to pydantic schemas, **ou
 
 > If a keyword had meaning across multiple types of backends, and if it means the same thing in all of those backends but has different names, then we use the `@@@`-style args so that the user can pass these args across all backends in the same way. Otherwise, the arguments in model_args are passed along verbatim.
 
-This argues for `@@@format@@@` as opposed to a dedicated `format` option in the method signature. Or, in the alternative, for an entir re-think of ModelArgs.
+This argues for `@@@format@@@` as opposed to a dedicated `format` option in the method signature. Or, in the alternative, for an entire re-think of ModelArgs.
 
 ## Integration with grammar-targeted LLMs
 

docs/examples/generative_slots/generative_slots.py

@@ -16,20 +16,19 @@ def generate_summary(text: str) -> str:
 
 
 if __name__ == "__main__":
-    m = start_session()
-    sentiment_component = classify_sentiment(m, text="I love this!")
-    print("Output sentiment is : ", sentiment_component)
-
-    summary = generate_summary(
-        m,
-        text="""
-        The eagle rays are a group of cartilaginous fishes in the family Myliobatidae,
-        consisting mostly of large species living in the open ocean rather than on the sea bottom.
-        Eagle rays feed on mollusks, and crustaceans, crushing their shells with their flattened teeth.
-        They are excellent swimmers and are able to breach the water up to several meters above the
-        surface. Compared with other rays, they have long tails, and well-defined, rhomboidal bodies.
-        They are ovoviviparous, giving birth to up to six young at a time. They range from 0.48 to
-        5.1 m (1.6 to 16.7 ft) in length and 7 m (23 ft) in wingspan.
-        """,
-    )
-    print("Generated summary is :", summary)
+    with start_session():
+        sentiment_component = classify_sentiment(text="I love this!")
+        print("Output sentiment is : ", sentiment_component)
+
+        summary = generate_summary(
+            text="""
+            The eagle rays are a group of cartilaginous fishes in the family Myliobatidae,
+            consisting mostly of large species living in the open ocean rather than on the sea bottom.
+            Eagle rays feed on mollusks, and crustaceans, crushing their shells with their flattened teeth.
+            They are excellent swimmers and are able to breach the water up to several meters above the
+            surface. Compared with other rays, they have long tails, and well-defined, rhomboidal bodies.
+            They are ovoviviparous, giving birth to up to six young at a time. They range from 0.48 to
+            5.1 m (1.6 to 16.7 ft) in length and 7 m (23 ft) in wingspan.
+            """
+        )
+        print("Generated summary is :", summary)

docs/examples/instruct_validate_repair/101_email.py

@@ -1,14 +1,17 @@
 # This is the 101 example for using `session` and `instruct`.
 # helper function to wrap text
 from docs.examples.helper import w
-from mellea import start_session
+from mellea import instruct, start_session
 from mellea.backends.types import ModelOption
 
 # create a session using Granite 3.3 8B on Ollama and a simple context [see below]
-m = start_session(model_options={ModelOption.MAX_NEW_TOKENS: 200})
+with start_session(model_options={ModelOption.MAX_NEW_TOKENS: 200}):
+    # write an email
+    email_v1 = instruct("Write an email to invite all interns to the office party.")
 
-# write an email
-email_v1 = m.instruct("Write an email to invite all interns to the office party.")
+with start_session(model_options={ModelOption.MAX_NEW_TOKENS: 200}) as m:
+    # write an email
+    email_v1 = m.instruct("Write an email to invite all interns to the office party.")
 
 # print result
 print(f"***** email ****\n{w(email_v1)}\n*******")

docs/examples/notebooks/compositionality_with_generative_slots.ipynb

@@ -33,8 +33,13 @@
     "!nohup ollama serve >/dev/null 2>&1 &\n",
     "\n",
     "from IPython.display import HTML, display\n",
-    "def set_css(): display(HTML('\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n'))\n",
-    "get_ipython().events.register('pre_run_cell',set_css)"
+    "\n",
+    "\n",
+    "def set_css():\n",
+    "    display(HTML(\"\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n\"))\n",
+    "\n",
+    "\n",
+    "get_ipython().events.register(\"pre_run_cell\", set_css)"
    ]
   },
   {
@@ -76,15 +81,18 @@
    "source": [
     "from mellea import generative\n",
     "\n",
+    "\n",
     "# The Summarizer Library\n",
     "@generative\n",
     "def summarize_meeting(transcript: str) -> str:\n",
     "    \"\"\"Summarize the meeting transcript into a concise paragraph of main points.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def summarize_contract(contract_text: str) -> str:\n",
     "    \"\"\"Produce a natural language summary of contract obligations and risks.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def summarize_short_story(story: str) -> str:\n",
     "    \"\"\"Summarize a short story, with one paragraph on plot and one paragraph on braod themes.\"\"\""
@@ -109,10 +117,12 @@
     "def propose_business_decision(summary: str) -> str:\n",
     "    \"\"\"Given a structured summary with clear recommendations, propose a business decision.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def generate_risk_mitigation(summary: str) -> str:\n",
     "    \"\"\"If the summary contains risk elements, propose mitigation strategies.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def generate_novel_recommendations(summary: str) -> str:\n",
     "    \"\"\"Provide a list of novel recommendations that are similar in plot or theme to the short story summary.\"\"\""
@@ -135,16 +145,19 @@
    "outputs": [],
    "source": [
     "# Compose the libraries.\n",
-    "from typing import Literal  # noqa: E402\n",
+    "from typing import Literal\n",
+    "\n",
     "\n",
     "@generative\n",
     "def has_structured_conclusion(summary: str) -> Literal[\"yes\", \"no\"]:\n",
     "    \"\"\"Determine whether the summary contains a clearly marked conclusion or recommendation.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def contains_actionable_risks(summary: str) -> Literal[\"yes\", \"no\"]:\n",
     "    \"\"\"Check whether the summary contains references to business risks or exposure.\"\"\"\n",
     "\n",
+    "\n",
     "@generative\n",
     "def has_theme_and_plot(summary: str) -> Literal[\"yes\", \"no\"]:\n",
     "    \"\"\"Check whether the summary contains both a plot and thematic elements.\"\"\""
@@ -166,7 +179,7 @@
    },
    "outputs": [],
    "source": [
-    "from mellea import start_session  # noqa: E402\n",
+    "from mellea import start_session\n",
     "\n",
     "m = start_session()"
    ]

docs/examples/notebooks/context_example.ipynb

@@ -33,8 +33,13 @@
     "!nohup ollama serve >/dev/null 2>&1 &\n",
     "\n",
     "from IPython.display import HTML, display\n",
-    "def set_css(): display(HTML('\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n'))\n",
-    "get_ipython().events.register('pre_run_cell',set_css)"
+    "\n",
+    "\n",
+    "def set_css():\n",
+    "    display(HTML(\"\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n\"))\n",
+    "\n",
+    "\n",
+    "get_ipython().events.register(\"pre_run_cell\", set_css)"
    ]
   },
   {
@@ -80,6 +85,7 @@
    "outputs": [],
    "source": [
     "from mellea import LinearContext, start_session\n",
+    "\n",
     "m = start_session(ctx=LinearContext())\n",
     "m.chat(\"Make up a math problem.\")\n",
     "m.chat(\"Solve your math problem.\")\n",

docs/examples/notebooks/document_mobject.ipynb

@@ -33,8 +33,13 @@
     "!nohup ollama serve >/dev/null 2>&1 &\n",
     "\n",
     "from IPython.display import HTML, display\n",
-    "def set_css(): display(HTML('\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n'))\n",
-    "get_ipython().events.register('pre_run_cell',set_css)"
+    "\n",
+    "\n",
+    "def set_css():\n",
+    "    display(HTML(\"\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n\"))\n",
+    "\n",
+    "\n",
+    "get_ipython().events.register(\"pre_run_cell\", set_css)"
    ]
   },
   {
@@ -77,6 +82,7 @@
    "outputs": [],
    "source": [
     "from mellea.stdlib.docs.richdocument import RichDocument\n",
+    "\n",
     "rd = RichDocument.from_document_file(\"https://arxiv.org/pdf/1906.04043\")"
    ]
   },
@@ -96,7 +102,8 @@
    },
    "outputs": [],
    "source": [
-    "from mellea.stdlib.docs.richdocument import Table  # noqa: E402\n",
+    "from mellea.stdlib.docs.richdocument import Table\n",
+    "\n",
     "table1: Table = rd.get_tables()[0]\n",
     "print(table1.to_markdown())"
    ]
@@ -119,8 +126,9 @@
    },
    "outputs": [],
    "source": [
-    "from mellea import start_session  # noqa: E402\n",
-    "from mellea.backends.types import ModelOption  # noqa: E402\n",
+    "from mellea import start_session\n",
+    "from mellea.backends.types import ModelOption\n",
+    "\n",
     "m = start_session()\n",
     "for seed in [x * 12 for x in range(5)]:\n",
     "    table2 = m.transform(\n",

docs/examples/notebooks/example.ipynb

@@ -33,8 +33,13 @@
     "!nohup ollama serve >/dev/null 2>&1 &\n",
     "\n",
     "from IPython.display import HTML, display\n",
-    "def set_css(): display(HTML('\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n'))\n",
-    "get_ipython().events.register('pre_run_cell',set_css)"
+    "\n",
+    "\n",
+    "def set_css():\n",
+    "    display(HTML(\"\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n\"))\n",
+    "\n",
+    "\n",
+    "get_ipython().events.register(\"pre_run_cell\", set_css)"
    ]
   },
   {
@@ -77,6 +82,7 @@
    "outputs": [],
    "source": [
     "import mellea\n",
+    "\n",
     "m = mellea.start_session()"
    ]
   },

docs/examples/notebooks/instruct_validate_repair.ipynb

@@ -33,8 +33,13 @@
     "!nohup ollama serve >/dev/null 2>&1 &\n",
     "\n",
     "from IPython.display import HTML, display\n",
-    "def set_css(): display(HTML('\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n'))\n",
-    "get_ipython().events.register('pre_run_cell',set_css)"
+    "\n",
+    "\n",
+    "def set_css():\n",
+    "    display(HTML(\"\\n<style>\\n pre{\\n white-space: pre-wrap;\\n}\\n</style>\\n\"))\n",
+    "\n",
+    "\n",
+    "get_ipython().events.register(\"pre_run_cell\", set_css)"
    ]
   },
   {
@@ -66,9 +71,9 @@
    "source": [
     "## Import Mellea and Specify Requirements\n",
     "We create 3 requirements:\n",
-    "- 1st requirement (r1) will be validated by LLM-as-a-judge on the output of the instruction. This is the default behavior.\n",
-    "- 2nd requirement (r2) uses a function that takes the output of a sampling step and returns a boolean value indicating successful or unsuccessful validation. While the validation_fn parameter requires to run validation on the full session context, Mellea provides a wrapper for simpler validation functions (simple_validate(fn: Callable[[str], bool])) that take the output string and return a boolean as seen in this case.\n",
-    "- 3rd requirement is a check(). Checks are only used for validation, not for generation. Checks aim to avoid the \"do not think about B\" effect that often primes models (and humans) to do the opposite and \"think\" about B."
+    "- First requirement (r1) will be validated by LLM-as-a-judge on the output of the instruction. This is the default behavior.\n",
+    "- Second requirement (r2) uses a function that takes the output of a sampling step and returns a boolean value indicating successful or unsuccessful validation. While the validation_fn parameter requires to run validation on the full session context, Mellea provides a wrapper for simpler validation functions (simple_validate(fn: Callable[[str], bool])) that take the output string and return a boolean as seen in this case.\n",
+    "- Third requirement is a check(). Checks are only used for validation, not for generation. Checks aim to avoid the \"do not think about B\" effect that often primes models (and humans) to do the opposite and \"think\" about B."
    ]
   },
   {
@@ -79,9 +84,10 @@
    },
    "outputs": [],
    "source": [
+    "import mellea\n",
     "from mellea.stdlib.requirement import check, req, simple_validate\n",
-    "import mellea  # noqa: E402\n",
-    "from mellea.stdlib.sampling import RejectionSamplingStrategy  # noqa: E402\n",
+    "from mellea.stdlib.sampling import RejectionSamplingStrategy\n",
+    "\n",
     "requirements = [\n",
     "    req(\"The email should have a salutation\"),  # == r1\n",
     "    req(\n",