Merge branch 'main' into hen/litellm_310

# Conflicts:
#	pyproject.toml
#	uv.lock

Author: HendrikStrobelt

.github/mergify.yml

@@ -0,0 +1,9 @@
+merge_protections:
+  - name: Enforce conventional commit
+    description: Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/
+    if:
+      - base = main
+    success_conditions:
+      - "title ~=
+        ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\\(.+\
+        \\))?:"

.github/workflows/quality.yml

@@ -0,0 +1,55 @@
+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.
+    env:
+      CICD: 1
+      OLLAMA_HOST: "127.0.0.1:5000"
+    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 --group dev
+      - name: Check style and run tests
+        run: pre-commit run --all-files
+      - name: Send failure message pre-commit
+        if: failure()  # This step will only run if a previous step failed
+        run: echo "The quality verification failed. Please run precommit "
+      - name: Install Ollama
+        run: curl -fsSL https://ollama.com/install.sh | sh
+      - name: Start serving ollama
+        run: nohup ollama serve &
+      - name: Pull Llama 3.2:1b model
+        run: ollama pull llama3.2:1b
+
+      - name: Run Tests
+        run: uv run -m pytest -v test
+      - name: Send failure message tests
+        if: failure()  # This step will only run if a previous step failed
+        run: echo "Tests failed. Please verify that tests are working locally."
+      

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`. If 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/agents/react.py

@@ -103,7 +103,7 @@ def react(
     react_toolbox: ReactToolbox,
 ):
     assert m.ctx.is_chat_context, "ReACT requires a chat context."
-    test_ctx_lin = m.ctx.linearize()
+    test_ctx_lin = m.ctx.render_for_generation()
     assert test_ctx_lin is not None and len(test_ctx_lin) == 0, (
         "ReACT expects a fresh context."
     )

docs/examples/agents/react_instruct.py

@@ -101,7 +101,7 @@ def react(
     react_toolbox: ReactToolbox,
 ):
     assert m.ctx.is_chat_context, "ReACT requires a chat context."
-    test_ctx_lin = m.ctx.linearize()
+    test_ctx_lin = m.ctx.render_for_generation()
     assert test_ctx_lin is not None and len(test_ctx_lin) == 0, (
         "ReACT expects a fresh context."
     )

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/generative_slots/inter_module_composition/summarizers.py

@@ -13,4 +13,4 @@ def summarize_contract(contract_text: str) -> str:
 
 @generative
 def summarize_short_story(story: str) -> str:
-    """Summarize a short story, with one paragraph on plot and one paragraph on braod themes."""
+    """Summarize a short story, with one paragraph on plot and one paragraph on broad themes."""

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,18 +81,21 @@
    "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.\"\"\""
+    "    \"\"\"Summarize a short story, with one paragraph on plot and one paragraph on broad 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()"
    ]