Merge pull request #33 from shcherbak-ai/dev

v0.6.1

Author: SergiiShcherbak

CHANGELOG.md

@@ -5,6 +5,10 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 
 - **Refactor**: Code reorganization that doesn't change functionality but improves structure or maintainability
 
+## [0.6.1](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.6.1) - 2025-06-04
+### Changed
+- Updated documentation for LM Studio models to clarify dummy API key requirement
+
 ## [0.6.0](https://github.com/shcherbak-ai/contextgem/releases/tag/v0.6.0) - 2025-06-03
 ### Added
 - LabelConcept - a classification concept type that categorizes content using predefined labels.

CONTRIBUTING.md

@@ -179,6 +179,7 @@ You **must** re-record cassettes if:
 - You modified any parameters in LLM API calls
 - You're writing a new test that calls the LLM API
 - The existing cassettes are no longer compatible with your changes
+- You made changes to local LLM API interactions (requires Ollama and LM Studio installed on your system)
 
 #### How to Re-record Cassettes
 
@@ -195,7 +196,9 @@ You **must** re-record cassettes if:
    ```
    CONTEXTGEM_LOGGER_LEVEL=DEBUG
    ```
-4. Run your tests, which will create new cassette files
+4. **For local LLM testing**: Install [Ollama](https://ollama.ai/) and [LM Studio](https://lmstudio.ai/) on your system if you're testing local model interactions
+
+5. Run your tests, which will create new cassette files
 
 **Important**: Re-recording cassettes will use your OpenAI API key and may incur charges to your account based on the number and type of API calls made during testing. Please be aware of these potential costs before re-recording.
 

contextgem/__init__.py

@@ -20,7 +20,7 @@
 ContextGem - Effortless LLM extraction from documents
 """
 
-__version__ = "0.6.0"
+__version__ = "0.6.1"
 __author__ = "Shcherbak AI AS"
 
 from contextgem.public import (

dev/notebooks/docs/concepts/date_concept/refs_and_justifications.ipynb

@@ -61,7 +61,7 @@
         "completion_date_concept = DateConcept(\n",
         "    name=\"Project completion date\",\n",
         "    description=\"The final completion date for the website redesign project\",\n",
-        "    add_justifications=True,  # enable justifications to understand extraction reasoning\n",
+        "    add_justifications=True,  # enable justifications to understand extraction logic\n",
         "    justification_depth=\"balanced\",\n",
         "    justification_max_sents=3,  # allow up to 3 sentences for the calculation justification\n",
         "    add_references=True,  # include references to source text\n",
@@ -74,11 +74,10 @@
         "\n",
         "# Configure DocumentLLM\n",
         "llm = DocumentLLM(\n",
-        "    model=\"azure/o4-mini\",\n",
+        "    model=\"azure/gpt-4.1\",\n",
         "    api_key=os.getenv(\"CONTEXTGEM_AZURE_OPENAI_API_KEY\"),\n",
         "    api_version=os.getenv(\"CONTEXTGEM_AZURE_OPENAI_API_VERSION\"),\n",
         "    api_base=os.getenv(\"CONTEXTGEM_AZURE_OPENAI_API_BASE\"),\n",
-        "    reasoning_effort=\"medium\",\n",
         ")\n",
         "\n",
         "# Extract the concept\n",

dev/requirements/requirements.dev.txt

@@ -26,7 +26,7 @@
 completion_date_concept = DateConcept(
     name="Project completion date",
     description="The final completion date for the website redesign project",
-    add_justifications=True,  # enable justifications to understand extraction reasoning
+    add_justifications=True,  # enable justifications to understand extraction logic
     justification_depth="balanced",
     justification_max_sents=3,  # allow up to 3 sentences for the calculation justification
     add_references=True,  # include references to source text
@@ -39,11 +39,10 @@
 
 # Configure DocumentLLM
 llm = DocumentLLM(
-    model="azure/o4-mini",
+    model="azure/gpt-4.1",
     api_key=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_KEY"),
     api_version=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_VERSION"),
     api_base=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_BASE"),
-    reasoning_effort="medium",
 )
 
 # Extract the concept

dev/requirements/requirements.main.txt

@@ -0,0 +1,10 @@
+from contextgem import DocumentLLM
+
+llm = DocumentLLM(
+    model="lm_studio/meta-llama-3.1-8b-instruct",
+    api_base="http://localhost:1234/v1",
+    api_key="dummy-key",  # dummy key to avoid connection error
+)
+
+# This is a known issue with calling LM Studio API in litellm:
+# https://github.com/openai/openai-python/issues/961

dev/usage_examples/docs/concepts/date_concept/refs_and_justifications.py

@@ -5894,7 +5894,7 @@ date information was inferred:
    completion_date_concept = DateConcept(
        name="Project completion date",
        description="The final completion date for the website redesign project",
-       add_justifications=True,  # enable justifications to understand extraction reasoning
+       add_justifications=True,  # enable justifications to understand extraction logic
        justification_depth="balanced",
        justification_max_sents=3,  # allow up to 3 sentences for the calculation justification
        add_references=True,  # include references to source text
@@ -5907,11 +5907,10 @@ date information was inferred:
 
    # Configure DocumentLLM
    llm = DocumentLLM(
-       model="azure/o4-mini",
+       model="azure/gpt-4.1",
        api_key=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_KEY"),
        api_version=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_VERSION"),
        api_base=os.getenv("CONTEXTGEM_AZURE_OPENAI_API_BASE"),
-       reasoning_effort="medium",
    )
 
    # Extract the concept
@@ -7613,6 +7612,29 @@ Using local LLM providers
        # see DocumentLLM API reference for all configuration options
    )
 
+Note:
+
+  **LM Studio Connection Error**: If you encounter a connection error
+  ("litellm.APIError: APIError: Lm_studioException - Connection
+  error") when using LM Studio, check that you have provided a dummy
+  API key. While API keys are usually not expected for local models,
+  this is a specific case where LM Studio requires one:LM Studio with
+  dummy API key
+
+     from contextgem import DocumentLLM
+
+     llm = DocumentLLM(
+         model="lm_studio/meta-llama-3.1-8b-instruct",
+         api_base="http://localhost:1234/v1",
+         api_key="dummy-key",  # dummy key to avoid connection error
+     )
+
+     # This is a known issue with calling LM Studio API in litellm:
+     # https://github.com/openai/openai-python/issues/961
+
+  This is a known issue with calling LM Studio API in litellm:
+  https://github.com/openai/openai-python/issues/961
+
 For a complete list of configuration options available when
 initializing DocumentLLM instances, see the next section Configuring
 LLM(s).
@@ -7687,6 +7709,29 @@ Using a local LLM
        # see DocumentLLM API reference for all configuration options
    )
 
+Note:
+
+  **LM Studio Connection Error**: If you encounter a connection error
+  ("litellm.APIError: APIError: Lm_studioException - Connection
+  error") when using LM Studio, check that you have provided a dummy
+  API key. While API keys are usually not expected for local models,
+  this is a specific case where LM Studio requires one:LM Studio with
+  dummy API key
+
+     from contextgem import DocumentLLM
+
+     llm = DocumentLLM(
+         model="lm_studio/meta-llama-3.1-8b-instruct",
+         api_base="http://localhost:1234/v1",
+         api_key="dummy-key",  # dummy key to avoid connection error
+     )
+
+     # This is a known issue with calling LM Studio API in litellm:
+     # https://github.com/openai/openai-python/issues/961
+
+  This is a known issue with calling LM Studio API in litellm:
+  https://github.com/openai/openai-python/issues/961
+
 
 📝 Configuration Parameters
 ===========================

dev/usage_examples/docs/llms/llm_init/lm_studio_connection_error_fix.py

@@ -22,7 +22,7 @@
 project = "ContextGem"
 copyright = "2025, Shcherbak AI AS"
 author = "Sergii Shcherbak"
-release = "0.6.0"
+release = "0.6.1"
 
 
 # Add path to the package

docs/docs-raw-for-llm.txt

@@ -40,6 +40,15 @@ For local models, usually you need to specify the ``api_base`` instead of the AP
    :language: python
    :caption: Using a local LLM
 
+.. note::
+   **LM Studio Connection Error**: If you encounter a connection error (``litellm.APIError: APIError: Lm_studioException - Connection error``) when using LM Studio, check that you have provided a dummy API key. While API keys are usually not expected for local models, this is a specific case where LM Studio requires one:
+
+   .. literalinclude:: ../../../dev/usage_examples/docs/llms/llm_init/lm_studio_connection_error_fix.py
+      :language: python
+      :caption: LM Studio with dummy API key
+
+   This is a known issue with calling LM Studio API in litellm: https://github.com/openai/openai-python/issues/961
+
 
 📝 Configuration Parameters
 -----------------------------

docs/source/conf.py

@@ -50,5 +50,14 @@ For local LLMs, you'll need to specify the provider, model name, and the appropr
    :language: python
    :caption: Using local LLM providers
 
+.. note::
+   **LM Studio Connection Error**: If you encounter a connection error (``litellm.APIError: APIError: Lm_studioException - Connection error``) when using LM Studio, check that you have provided a dummy API key. While API keys are usually not expected for local models, this is a specific case where LM Studio requires one:
+
+   .. literalinclude:: ../../../dev/usage_examples/docs/llms/llm_init/lm_studio_connection_error_fix.py
+      :language: python
+      :caption: LM Studio with dummy API key
+
+   This is a known issue with calling LM Studio API in litellm: https://github.com/openai/openai-python/issues/961
+
 
 For a complete list of configuration options available when initializing DocumentLLM instances, see the next section :doc:`llm_config`.