Merge branch 'main' into security_poc

Author: nrfulton

CHANGELOG.md

@@ -1,3 +1,22 @@
+## [v0.2.1](https://github.com/generative-computing/mellea/releases/tag/v0.2.1) - 2025-12-10
+
+### Feature
+
+* Test-based Evaluation with LLM-as-a-judge ([#225](https://github.com/generative-computing/mellea/issues/225)) ([`0f1f0f8`](https://github.com/generative-computing/mellea/commit/0f1f0f8eb12e60f7940e3ad5b40ce91ded73fc88))
+* Add a `code_interpreter` tool ([#232](https://github.com/generative-computing/mellea/issues/232)) ([`b03c964`](https://github.com/generative-computing/mellea/commit/b03c96439501146965cd123ce5046f2c5907acfb))
+
+### Fix
+
+* Add simple lock to hf generation to prevent using incorrect weights ([#237](https://github.com/generative-computing/mellea/issues/237)) ([`6b2a527`](https://github.com/generative-computing/mellea/commit/6b2a5276a426be87ce02fa89f49818535f211fa6))
+* Collection of small fixes ([#238](https://github.com/generative-computing/mellea/issues/238)) ([`2120112`](https://github.com/generative-computing/mellea/commit/2120112ee807da4e980eabc0df54b3aae12d2cd2))
+* Fix unused litellm import ([#246](https://github.com/generative-computing/mellea/issues/246)) ([`633bfd7`](https://github.com/generative-computing/mellea/commit/633bfd7198eac45f8c163fefcc910d9bf8a76151))
+* Minor updates to answer relevance ([#245](https://github.com/generative-computing/mellea/issues/245)) ([`bde9b4d`](https://github.com/generative-computing/mellea/commit/bde9b4dd91ab92af0f7a661e321bb9d701da0589))
+* Pre-commit file selection ([#243](https://github.com/generative-computing/mellea/issues/243)) ([`e70d307`](https://github.com/generative-computing/mellea/commit/e70d3075f92152f8bb1a519687575fc7f30ffe1b))
+
+### Documentation
+
+* Fixed copyright in LICENSE ([#210](https://github.com/generative-computing/mellea/issues/210)) ([`3087051`](https://github.com/generative-computing/mellea/commit/3087051f5fc102bb8e0319af6baf9d7a0222e6ef))
+
 ## [v0.2.0](https://github.com/generative-computing/mellea/releases/tag/v0.2.0) - 2025-11-19
 
 ### Feature

docs/examples/intrinsics/answer_relevance.py

@@ -0,0 +1,26 @@
+"""
+Example usage of the answer relevance intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/answer_relevance.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext, Document
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = ChatContext().add(Message("user", "Who attended the meeting?"))
+documents = [
+    Document("Meeting attendees: Alice, Bob, Carol."),
+    Document("Meeting time: 9:00 am to 11:00 am."),
+]
+original_result = "Many people attended the meeting."
+
+print(f"Result before relevance intrinsic: {original_result}")
+result = rag.rewrite_answer_for_relevance(original_result, documents, context, backend)
+print(f"Result after relevance intrinsic: {result}")

docs/examples/intrinsics/answerability.py

@@ -0,0 +1,28 @@
+"""
+Example usage of the answerability intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/answerability.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext, Document
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = ChatContext().add(Message("assistant", "Hello there, how can I help you?"))
+next_user_turn = "What is the square root of 4?"
+documents_answerable = [Document("The square root of 4 is 2.")]
+documents_unanswerable = [Document("The square root of 8 is not 2.")]
+
+result = rag.check_answerability(next_user_turn, documents_answerable, context, backend)
+print(f"Result of answerability check when answer is in documents: {result}")
+
+result = rag.check_answerability(
+    next_user_turn, documents_unanswerable, context, backend
+)
+print(f"Result of answerability check when answer is not in documents: {result}")

docs/examples/intrinsics/citations.py

@@ -0,0 +1,77 @@
+"""
+Example usage of the citations intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/citations.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext, Document
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+import json
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = ChatContext().add(
+    Message(
+        "user",
+        "How does Murdoch's expansion in Australia compare to his expansion "
+        "in New Zealand?",
+    )
+)
+assistant_response = (
+    "Murdoch expanded in Australia and New Zealand by acquiring and expanding local "
+    "newspapers. I do not have information about his expansion in New Zealand after "
+    "purchasing The Dominion."
+)
+documents = [
+    Document(
+        doc_id="1",
+        text="Keith Rupert Murdoch was born on 11 March 1931 in Melbourne, Australia, "
+        "the son of Sir Keith Murdoch (1885-1952) and Dame Elisabeth Murdoch (nee "
+        "Greene; 1909-2012). He is of English, Irish, and Scottish ancestry. Murdoch's "
+        "parents were also born in Melbourne. Keith Murdoch was a war correspondent "
+        "and later a regional newspaper magnate owning two newspapers in Adelaide, "
+        "South Australia, and a radio station in a faraway mining town. Following his "
+        "father's death, when he was 21, Murdoch returned from Oxford to take charge "
+        "of the family business News Limited, which had been established in 1923. "
+        "Rupert Murdoch turned its Adelaide newspaper, The News, its main asset, into "
+        "a major success. He began to direct his attention to acquisition and "
+        "expansion, buying the troubled Sunday Times in Perth, Western Australia "
+        "(1956) and over the next few years acquiring suburban and provincial "
+        "newspapers in New South Wales, Queensland, Victoria and the Northern "
+        "Territory, including the Sydney afternoon tabloid, The Daily Mirror (1960). "
+        'The Economist describes Murdoch as "inventing the modern tabloid", as he '
+        "developed a pattern for his newspapers, increasing sports and scandal "
+        "coverage and adopting eye-catching headlines. Murdoch's first foray outside "
+        "Australia involved the purchase of a controlling interest in the New Zealand "
+        "daily The Dominion. In January 1964, while touring New Zealand with friends "
+        "in a rented Morris Minor after sailing across the Tasman, Murdoch read of a "
+        "takeover bid for the Wellington paper by the British-based Canadian newspaper "
+        "magnate, Lord Thomson of Fleet. On the spur of the moment, he launched a "
+        "counter-bid. A four-way battle for control ensued in which the 32-year-old "
+        "Murdoch was ultimately successful. Later in 1964, Murdoch launched The "
+        "Australian, Australia's first national daily newspaper, which was based "
+        "first in Canberra and later in Sydney. In 1972, Murdoch acquired the Sydney "
+        "morning tabloid The Daily Telegraph from Australian media mogul Sir Frank "
+        "Packer, who later regretted selling it to him. In 1984, Murdoch was appointed "
+        "Companion of the Order of Australia (AC) for services to publishing. In 1999, "
+        "Murdoch significantly expanded his music holdings in Australia by acquiring "
+        "the controlling share in a leading Australian independent label, Michael "
+        "Gudinski's Mushroom Records; he merged that with Festival Records, and the "
+        "result was Festival Mushroom Records (FMR). Both Festival and FMR were "
+        "managed by Murdoch's son James Murdoch for several years.",
+    ),
+    Document(
+        doc_id="2",
+        text="This document has nothing to do with Rupert Murdoch. This document is "
+        "two sentences long.",
+    ),
+]
+
+
+result = rag.find_citations(assistant_response, documents, context, backend)
+print(f"Result of citations intrinsic:\n{json.dumps(result, indent=2)}")

docs/examples/intrinsics/context_relevance.py

@@ -0,0 +1,31 @@
+"""
+Example usage of the context relevance intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/context_relevance.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext, Document
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = ChatContext()
+question = "Who is the CEO of Microsoft?"
+document = Document(
+    # Document text does not say who is the CEO.
+    "Microsoft Corporation is an American multinational corporation and technology "
+    "conglomerate headquartered in Redmond, Washington.[2] Founded in 1975, the "
+    "company became influential in the rise of personal computers through software "
+    "like Windows, and the company has since expanded to Internet services, cloud "
+    "computing, video gaming and other fields. Microsoft is the largest software "
+    "maker, one of the most valuable public U.S. companies,[a] and one of the most "
+    "valuable brands globally."
+)
+
+result = rag.check_context_relevance(question, document, context, backend)
+print(f"Result of context relevance check: {result}")

docs/examples/intrinsics/hallucination_detection.py

@@ -0,0 +1,34 @@
+"""
+Example usage of the hallucination detection intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/hallucination_detection.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext, Document
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+import json
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = (
+    ChatContext()
+    .add(Message("assistant", "Hello there, how can I help you?"))
+    .add(Message("user", "Tell me about some yellow fish."))
+)
+
+assistant_response = "Purple bumble fish are yellow. Green bumble fish are also yellow."
+
+documents = [
+    Document(
+        doc_id="1",
+        text="The only type of fish that is yellow is the purple bumble fish.",
+    )
+]
+
+result = rag.flag_hallucinated_content(assistant_response, documents, context, backend)
+print(f"Result of hallucination check: {json.dumps(result, indent=2)}")

docs/examples/intrinsics/query_rewrite.py

@@ -0,0 +1,41 @@
+"""
+Example usage of the query rewrite intrinsic for RAG applications.
+
+To run this script from the root of the Mellea source tree, use the command:
+```
+uv run python docs/examples/intrinsics/query_rewrite.py
+```
+"""
+
+from mellea.backends.huggingface import LocalHFBackend
+from mellea.stdlib.base import ChatContext
+from mellea.stdlib.chat import Message
+from mellea.stdlib.intrinsics import rag
+
+
+backend = LocalHFBackend(model_id="ibm-granite/granite-3.3-2b-instruct")
+context = (
+    ChatContext()
+    .add(Message("assistant", "Welcome to pet questions!"))
+    .add(Message("user", "I have two pets, a dog named Rex and a cat named Lucy."))
+    .add(
+        Message(
+            "assistant",
+            "Rex spends a lot of time in the backyard and outdoors, "
+            "and Luna is always inside.",
+        )
+    )
+    .add(
+        Message(
+            "user",
+            "Sounds good! Rex must love exploring outside, while Lucy "
+            "probably enjoys her cozy indoor life.",
+        )
+    )
+)
+next_user_turn = "But is he more likely to get fleas because of that?"
+
+print(f"Original user question: {next_user_turn}")
+
+result = rag.rewrite_question(next_user_turn, context, backend)
+print(f"Rewritten user question: {result}")

mellea/stdlib/genslot.py

@@ -204,7 +204,17 @@ def bind_function_arguments(
         Dictionary mapping parameter names to bound values with defaults applied.
     """
     signature = inspect.signature(func)
-    bound_arguments = signature.bind(*args, **kwargs)
+    try:
+        bound_arguments = signature.bind(*args, **kwargs)
+    except TypeError as e:
+        # Provide a clear error message when parameters from the original function are missing
+        if "missing" in str(e) and "required" in str(e):
+            raise TypeError(
+                f"generative slot is missing required parameter(s) from the original function '{func.__name__}': {e}"
+            ) from e
+
+        # Else re-raise the error if it's not the expected error.
+        raise e
     bound_arguments.apply_defaults()
     return dict(bound_arguments.arguments)
 
@@ -346,10 +356,22 @@ def _context_backend_extract_args_and_kwargs(
             using_session_overload = True
 
         # Call the appropriate function and let python handle the arg/kwarg extraction.
-        if using_session_overload:
-            extracted = _session_extract_args_and_kwargs(*args, **kwargs)
-        else:
-            extracted = _context_backend_extract_args_and_kwargs(*args, **kwargs)
+        try:
+            if using_session_overload:
+                extracted = _session_extract_args_and_kwargs(*args, **kwargs)
+            else:
+                extracted = _context_backend_extract_args_and_kwargs(*args, **kwargs)
+        except TypeError as e:
+            # Provide a clear error message when required mellea parameters are missing
+            if "missing" in str(e) and (
+                "context" in str(e) or "backend" in str(e) or "m" in str(e)
+            ):
+                raise TypeError(
+                    "generative slot requires either a MelleaSession (m=...) or both a Context and Backend (context=..., backend=...) to be provided as the first argument(s)"
+                ) from e
+
+            # If it's not the expected err, simply re-raise it.
+            raise e
 
         if len(extracted.f_args) > 0:
             raise TypeError(

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "mellea"
-version = "0.2.0"
+version = "0.2.1"
 authors = [
     { name = "Nathan Fulton", email = "[email protected]" },
     { name = "Hendrik Strobelt", email = "[email protected]" },