feat: simplify intrinsics (code and examples)

[jakelorocco]

Misc PR

Type of PR

• Bug Fix
• New Feature
• Documentation
• Other

Description

• Link to Issue: Fixes N/A

I will likely have to fix merge conflicts between this and the other granite switch pr. I would ideally like to merge this first.

Changes:

• Add changes to start_session to simplify setting context_type.
• Added start_backend to do the same thing that start_session does but not wrap it in a session
• simplified the document parameters for intrinsic functions
• simplified the intrinsic examples by removing unnecessary mellea imports
• ensured existing intrinsic examples work with new easy use parameters, etc...

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code as added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

[github-actions]

The PR description has been updated. Please fill out the template for your PR to be reviewed.

[ajbozarth]

Three inline comments below. General notes:

Circular import pattern (start_backend.py ↔ session.py): session.py does a top-level import of start_backend, while start_backend.py defers its import of _resolve_backend_and_context inside the function body to avoid the cycle. Works at runtime, but fragile — the impl file depends on a private helper from another module. Cleaner to move _resolve_backend_and_context / _resolve_context into a _session_util.py that both files import independently.

Merge surface with #881: Both PRs touch _util.py, rag.py, and all the docs/examples/intrinsics/ files. The changes are orthogonal (this PR adds the coerce/resolve helpers; #881 extends call_intrinsic to support OpenAIBackend) but the merge will need care to keep both. Also: citations.py here drops the explicit doc_id="1" / doc_id="2" in favour of auto_doc_id=True (0-indexed). #881 also modifies that file — verify the final merged example has consistent IDs and matches whatever the intrinsic test fixtures expect.

Return type fixes — rewrite_question and check_context_relevance were both typed -> float; now correctly -> str. Good catches.

[ajbozarth]

Regression: this constructs the backend (including passing model_options to the constructor) before the SESSION_PRE_INIT hook runs. In the original code the hook ran first and the backend was built with the hook's (potentially modified) model_options. Now the hook updates the local model_options variable on line 291 but the backend never sees it.

Fix: split this helper — call _resolve_context here for early argument validation, then construct the backend after the hook block.

[jakelorocco]

Resolved; split functionality up and calling the backend creation post hook.

[jakelorocco]

@ajbozarth

Circular import pattern (start_backend.py ↔ session.py): session.py does a top-level import of start_backend, while start_backend.py defers its import of _resolve_backend_and_context inside the function body to avoid the cycle. Works at runtime, but fragile — the impl file depends on a private helper from another module. Cleaner to move _resolve_backend_and_context / _resolve_context into a _session_util.py that both files import independently.

Fixed the circular imports. Split up functionality and moved everything to start backend. We don't need a separate utils function. session can just import from start_backend.

Merge surface with #881: Both PRs touch _util.py, rag.py, and all the docs/examples/intrinsics/ files. The changes are orthogonal (this PR adds the coerce/resolve helpers; #881 extends call_intrinsic to support OpenAIBackend) but the merge will need care to keep both. Also: citations.py here drops the explicit doc_id="1" / doc_id="2" in favour of auto_doc_id=True (0-indexed). #881 also modifies that file — verify the final merged example has consistent IDs and matches whatever the intrinsic test fixtures expect.

I tested all intrinsic examples. Functionality is the same. I will resolve merge conflicts in the other PR. This PR takes precedence.

[ajbozarth]

All three issues from the previous round are addressed — hook ordering fixed, unreachable assert removed, misleading comment removed. One remaining concern with no specific line to attach: the hook ordering fix has no regression test. A unit test that patches invoke_hook to mutate model_options and asserts the backend was constructed with the updated value would lock this in.

[ajbozarth]

session.py imports start_backend here but never calls it. The only effect is exposing mellea.stdlib.session.start_backend as an importable path, which test_session_unit.py relies on. Remove this import and update the test to import from the canonical location (mellea.stdlib.start_backend or mellea) instead.

[ajbozarth]

This error references start_session's docstring, but this is start_backend. Either point to start_backend or list the valid backend names inline — they're short enough.