llmflock 0.0.2__tar.gz

llmflock-0.0.2/LICENSE.txt

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

llmflock-0.0.2/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: llmflock
+Version: 0.0.2
+Summary: LLM Runner Control is a CLI tool to interact with local and remote LLM, define multiple scenario variations (model × prompt × options), run it over a dataset and capture structured results for comparison or to build knowledge through meta analysis.
+License-File: LICENSE.txt
+Requires-Dist: jsonschema
+Requires-Dist: llm
+Requires-Dist: llm-gpt4all
+Requires-Dist: llm-ollama
+Requires-Dist: ollama
+Requires-Dist: python-dotenv
+Requires-Dist: PyYAML
+Dynamic: license-file

llmflock-0.0.2/README.md

@@ -0,0 +1,48 @@
+# LLM Runner Control
+
+A CLI tool to interact with local and remote LLM, define multiple scenario variations (model × prompt × options), run it over a dataset and capture structured results for comparison or to build knowledge through meta analysis.
+
+DRAFT: more on the objective of this tool: it is built to run extraction the same structured data (`data_schemas.default`) in a list (`datasets.default`) of documents (`document_sets.default`) usings LLM and output tabular data. It is designed to run the extraction several times - or variations - (`scenarios.default.variations`) with different models, prompts or model options (temperature, top_p). It also designed to repeat one variation several times (reference to non-deterministic behaviour of LLMs...) (`scenarios.default.variations.repeat`).
+
+Note: actually this is not limited to extraction of structured data (ie a task where the research data is already in the input document but drowned in it), but to any task which generate structured data (because then structured data can then be easily compared/assessed)
+
+Note 2: maybe that tool is more aimed at smaller models (local or cloud-hosted). By design it will have to be run **very** repetitively on big dataset so cost of running huge models from the frontier labs can be dissuasive. But big models need to be tested too sometimes to make sure the small models jobs remains relevant.
+
+Note 3: how to we rate and compare (benchmark) the resulting output structured data, what will be the coverage of the comparison part of this tool?
+
+- wanted to find an example of llm comparison tool: found [this one](https://www.simonpcouch.com/blog/2025-04-01-gemini-2-5-pro) (here applied to Gemini 2.5 Pro) from Simon P. Couch ([via](https://simonwillison.net/2026/Jan/20/electricity-use-of-ai-coding-agents/) then [via](https://www.simonpcouch.com/blog/2026-01-20-cc-impact/)) : which lead me to a even more popular approach ? [https://inspect.aisi.org.uk/] .....  take-aways are:
+  - use a repeat parameter (epoch) to "Evaluate each sample multiple times to better quantify variation"
+
+Note 4: more thought one the viewing result part: need to have a tool to aggregate results, adding comparison with one selected IDEAL run and output all of it in a easy spreadsheet format (csv, excel) for further analysis and visualization. by design, the tool will produce was amount of llm-generated data (over dataset and multiple variation) and exact match is illusionist / unrealistic goal. While study of individual result is still valuable to understand, an essential metric is CONVERGENCE, not EQUALITY when comparing generated data.
+
+Hence that tool `llmrunctl` aim to keep it to minimum, focusing on the run+extract part.
+
+
+**On where it sits in the ecosystem of LLM tools:** It is a LLM gateway: meaning it can call different LLM providers (local inference framework or cloud-hosted) with a rudimentary plugin system. If the project matures enough it could be beneficial the transition to a more established LLM gateway tool (like liteLLm, anyLLM).
+
+
+## Getting started
+
+1. [Ollama](https://ollama.com/download) should be installed and running
+2. Clone the repository and install it with pip: `pip install .` (At this stage the package is not distributed, ie not published to PyPI, hence cannot be installed directly from PyPI)
+    1. Or use `pip install -e .` if you want to install in editable mode.
+
+## Usage
+
+To run the example in `data/example1-ev`, use the command: `llmr --configfile=data/example1-ev/config.yaml` or `llmr --configfile=data/example1-ev/config.yaml --debug`
+
+### Examples
+
+- submitting a prompt: `llmrunctl "extract Company and Location entities in JSON format from the following text: 'EU clears merger of Essilor , Luxottica without conditions'"`
+- switch from the default model: `llmrunctl "extract Company and Location entities in JSON format from the following text: 'EU clears merger of Essilor , Luxottica without conditions'" -m gpt-oss` (note: the model need to be defined in the default config)
+- specify repeat count: `llmrunctl "extract Company and Location entities in JSON format from the following text: 'EU clears merger of Essilor , Luxottica without conditions'" -r 3`
+- specify a CSV dataset: `llmrunctl --prompt-filename=data/example4-noconfig/PROMPT.md --dataset-filename=data/example4-noconfig/dataset.csv`
+- specify a schema: `llmrunctl --prompt-filename=data/example4-noconfig/PROMPT.dates.md --dataset-filename=data/example4-noconfig/dataset.dates.csv --schema 'start int NULL, end int NULL'`
+  - `llmrunctl "What years mark the start and end of Queen Elizabeth II's reign in the United Kingdom?" --schema 'start int, end int'`
+  - `llmrunctl "What years mark the start and end of King Charles III's reign in the United Kingdom?" --schema 'start int NULL, end int NULL'`
+- specify a multi-schema: `llmrunctl --prompt-filename=data/example4-noconfig/PROMPT.borders.md --dataset-filename=data/example4-noconfig/dataset.borders.csv --schema-multi 'name str'`
+
+- There are also currently 3 working examples based on provided config file (and associated data):
+- `llmrunctl --configfile=data/example1-ev/config.yaml`
+- `llmrunctl --configfile=data/example2-img-transform/config.yaml`
+- `llmrunctl --configfile=data/example3-finance/config.yaml`

llmflock-0.0.2/llmflock/__main__.py

@@ -0,0 +1,4 @@
+from .cli import cli
+
+if __name__ == "__main__":
+    cli()

llmflock-0.0.2/llmflock/cli.py

@@ -0,0 +1,506 @@
+import argparse
+import csv
+import itertools
+import re
+
+import llmflock.config as config_module
+from llmflock.concise_schema.utils_external import schema_dsl
+from llmflock.concise_schema.prompt_instructions import build_schema_prompt
+import json
+import os
+from datetime import datetime
+from time import perf_counter
+from copy import deepcopy
+from jsonschema import validate, ValidationError
+
+# from dotenv import load_dotenv
+# WIP: about adding another provider (openrouter)
+
+import logging
+import yaml
+from llmflock.ollama_ollama import ollama_ollama_call
+from llmflock.simonw_llm import simonw_llm_call
+
+logger = logging.getLogger(__name__)
+
+parser = argparse.ArgumentParser(
+    description="Run multiple LLM scenarios over dataset.")
+parser.add_argument('prompt', nargs='?', default=None,
+                    help="Prompt text to submit (mandatory when no --configfile is given)")
+parser.add_argument('-d', '--debug', action='store_true', default=False,
+                    help="keep LLM prompts, responses, execution time (+...)")
+parser.add_argument('--dry-run', action='store_true', default=False,)
+parser.add_argument('-c', '--configfile', default=None,
+                    help="Specify the configuration file to use (without it, the built-in default config is used)")
+parser.add_argument('--scenario', default='default',
+                    help="Specify the scenario to run (see config.yaml)")
+parser.add_argument('--dataset-filename', default=None,
+                    help="Override the dataset file specified in config.yaml")
+parser.add_argument('--prompt-filename', default=None,
+                    help="Override the prompt template file specified in config.yaml")
+parser.add_argument('-m', '--model', default=None,
+                    help="Override the models specified in config.yaml (Comma-separated list of model names)")
+parser.add_argument('-r', '--repeats', type=int, default=None,
+                    help="Override the number of repeats of each variation")
+parser.add_argument('--schema', default=None,
+                    help="Override the JSON schema")
+parser.add_argument('--schema-multi', default=None,
+                    help="Override the JSON schema")
+args = parser.parse_args()
+
+# Ollama-powered models all accept the Ollama modelfile parameters as options
+# see: https://github.com/ollama/ollama/blob/main/docs/modelfile.md#parameter
+
+# Hard-coded max tokens (never part of the variations)
+# TODO: move somewhere else?
+MAX_PREDICT_TOKENS = 8192
+
+# trying to stick to [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html)
+
+
+def logger_debug_file(content, filename, directory=None):
+    """Write debug text to a file in the specified directory."""
+    if args.debug:
+        if directory is None:
+            directory = config_module.log_dir
+        with open(os.path.join(directory, filename), 'w') as f:
+            f.write(content)
+        logger.debug(f"File saved: {os.path.join(directory, filename)}")
+
+
+
+def build_prompt(template: str, variables: dict) -> str:
+    """ Template processing function to build the prompt.
+
+    :param template:
+    :param variables:
+    :return:
+    """
+    # No variable at all (eg a prompt submitted directly on the command line):
+    # the template IS the prompt. Skipping .format() also keeps any literal
+    # brace of that prompt intact.
+    if not variables:
+        return template
+
+    # if a variable name is suffixed by "_filename", load the file content
+    # into a new variable named without that suffix (eg "doc_content_filename"
+    # -> "doc_content")
+    variables_loaded = {}
+    for k, v in variables.items():
+        if k.endswith('_filename'):
+            var_name = k[:-len('_filename')]
+            with open(v, 'r') as file:
+                variables_loaded[var_name] = file.read()
+        else:
+            variables_loaded[k] = v
+
+    prompt = template.format(**variables_loaded)
+    # for k, v in vars.items():
+    #     placeholder = f'<{k}>'
+    #     prompt = prompt.replace(placeholder, v)
+
+    return prompt
+
+
+def extract_validate_json(text: str, schema: dict) -> dict:
+    extraction = {
+        'status': 0,
+        'message': None,
+        'data': {},
+    }
+    json_match = re.findall(r"```json\n(.*?)\n```", text, re.DOTALL)
+    if json_match:
+        logger.debug('JSON code block found in LLM response')
+        # Extract the JSON content from the last match
+        # Note: we use the last match to avoid issues with multiple JSON
+        # blocks in the response
+        json_content = json_match[-1].strip()
+
+        try:
+            extraction['data'] = json.loads(json_content)
+            validate(instance=extraction['data'], schema=schema)
+
+        except json.JSONDecodeError as e:
+            logger.error(f'Invalid JSON from LLM: {str(e)}')
+            logger.error(f'Raw JSON content: {json_content[:200]}...')
+            extraction['message'] = f'Invalid JSON from LLM: {str(e)} ; Raw JSON content: {json_content[:200]}...'
+            extraction['status'] = 2
+        except ValidationError as e:
+            logger.error(f'JSON does not conform to schema: {str(e)}')
+            logger.error(f'Extracted JSON content: {json_content[:200]}...')
+            extraction['message'] = f'JSON does not conform to schema: {str(e)} ; Extracted JSON content: {json_content[:200]}...'
+            extraction['status'] = 3
+    else:
+        logger.error(f'Failed to extract JSON fenced-block from LLM response')
+        extraction['message'] = 'Failed to extract JSON fenced-block from LLM response'
+        extraction['status'] = 1
+
+    return extraction
+
+
+def call_llm(prompt: str, model_config: dict, model_options: dict) -> dict:
+    # generate options by mapping model_options keys to model specific option keys
+    model_options_specific = {}
+    for key, value in model_options.items():
+        if key in model_config['options']:
+            model_options_specific[model_config['options'][key]] = value
+
+    # call appropriate backend
+    if model_config['backend'] == 'ollama_ollama':
+        response = ollama_ollama_call(prompt, model_config['name'],
+                                  model_options_specific)
+    elif model_config['backend'] == 'simonw_llm':
+        response = simonw_llm_call(prompt, model_config['name'],
+                               model_options_specific)
+    else:
+        raise ValueError(f"Unknown backend: {model_config['backend']}")
+
+    return response
+
+
+def build_variations(scenario_variations: dict) -> list:
+    """Build the list of variations to run (the "matrix"), one dict per LLM call
+    (per dataset record).
+
+    Every parameter is optional but `prompts`: an omitted parameter simply
+    contributes a single "unset" value to the product.
+
+    :param scenario_variations: the `variations` object of the active scenario
+    :return: the flat list of variations, in nested-loop order
+    """
+    document_sets = scenario_variations.get('document_sets') or [None]
+    prompts = scenario_variations.get('prompts') or []
+    prompt_const_embeds = scenario_variations.get('prompt_const_embeds') or [None]
+    models = scenario_variations.get('models')
+    model_options_config = scenario_variations.get('model_options') or {}
+    repeats = scenario_variations.get('repeats', 1)
+
+    # the model options are generic: any key defined in the scenario is a
+    # dimension of the matrix, none of them is mandatory.
+    option_names = list(model_options_config.keys())
+    option_value_combinations = list(itertools.product(
+        *[model_options_config[name] for name in option_names]))
+
+    variations = []
+    for (document_set, prompt, prompt_const_embed, model, option_values,
+         repeat) in itertools.product(document_sets, prompts,
+                                      prompt_const_embeds, models,
+                                      option_value_combinations,
+                                      range(1, repeats + 1)):
+        variations.append({
+            'document_set': document_set,
+            'prompt': prompt,
+            'prompt_const_embed': prompt_const_embed,
+            'model': model,
+            'model_options': dict(zip(option_names, option_values)),
+            'repeat': repeat,
+        })
+
+    return variations
+
+
+def variations_breakdown(scenario_variations: dict) -> str:
+    """Human readable breakdown of the variations matrix (eg "1 document set x
+    2 prompt x 1 model x 3 temperature x 1 repeat")."""
+    factors = [
+        (len(scenario_variations.get('document_sets') or [None]), 'document set'),
+        (len(scenario_variations.get('prompts') or []), 'prompt'),
+        (len(scenario_variations.get('prompt_const_embeds') or [None]), 'prompt const embed'),
+        (len(scenario_variations.get('models') or [None]), 'model'),
+    ]
+    for parameter, values in (scenario_variations.get('model_options') or {}).items():
+        factors.append((len(values), parameter))
+    factors.append((scenario_variations.get('repeats', 1), 'repeat'))
+
+    return ' x '.join(f'{count} {label}' for count, label in factors)
+
+
+def variation_label(variation: dict) -> dict:
+    """The identity of a variation, as stored in output.jsonl and used to name
+    the debug files."""
+    document_set = variation['document_set']
+    prompt_const_embed = variation['prompt_const_embed']
+    return {
+        'document': document_set['name'] if document_set else None,
+        'prompt': variation['prompt']['name'],
+        'prompt_const_embed': prompt_const_embed['name'] if prompt_const_embed else None,
+        'model': variation['model'],
+        'model_options': variation['model_options'],
+        'repeat': variation['repeat'],
+    }
+
+
+def variation_slug(data_id, label: dict) -> str:
+    """Filename-friendly rendering of a variation label."""
+    options = '-'.join(f'{name}{value}'
+                       for name, value in label['model_options'].items())
+    parts = [str(data_id), str(label['document']), str(label['prompt']),
+             str(label['prompt_const_embed']), str(label['model'])]
+    if options:
+        parts.append(options)
+    parts.append(f'repeat{label["repeat"]}')
+    return '-'.join(parts)
+
+
+def run_variation(data: dict, variation: dict, models: dict, schema: dict | None):
+    """Run a single variation for a single dataset record (one LLM call)."""
+    data_id = data.get('id')
+    label = variation_label(variation)
+
+    # the document set is optional: without it the record carries no
+    # variation-specific data
+    document_set = variation['document_set']
+    if document_set is None:
+        document = {}
+    else:
+        docs_by_id = {}
+        # For later: for each run of run_variations (ie for each data item)
+        # we are doing this load file operation for the same file. I note that
+        # it can be optimized but I think there may be not significant gain in
+        # the overall performance of the process. So keeping it simple for now.
+        with open(document_set['filename'], 'r') as infile:
+            for line in infile:
+                if not line.strip():
+                    continue
+                item = json.loads(line.strip())
+                docs_by_id[item['id']] = item
+        document = docs_by_id[data_id]
+
+    # the prompt template is either passed directly ('content')
+    #  or read from a file ('filename')
+    template = variation['prompt']['template']
+    if template.get('content') is not None:
+        prompt_template = template['content']
+    else:
+        with open(template['filename'], 'r') as file:
+            prompt_template = file.read()
+
+    prompt_const_embed = variation['prompt_const_embed']
+    if prompt_const_embed is None:
+        const_embed_variables = {}
+    else:
+        # convert to the "<var_name>_filename" convention expected by build_prompt
+        const_embed_variables = {
+            f'{var_name}_filename': var_config['filename']
+            for var_name, var_config in prompt_const_embed['variables'].items()
+        }
+
+    variables = {**data, **document, **const_embed_variables}
+    prompt = build_prompt(prompt_template, variables)
+
+    # the prompt only depends on the record + document set + prompt + const
+    # embed, hence the shorter filename here
+    logger_debug_file(prompt, 'prompt-{}-{}-{}-{}.md'.format(
+        data_id, label['document'], label['prompt'], label['prompt_const_embed']))
+
+    model_config = models[variation['model']]
+    model_options = {**variation['model_options'],
+                     'max_predict_tokens': MAX_PREDICT_TOKENS}
+
+    print('LLM Call for id={} doc={}, prompt={}, const_embed={}, model={}, options={}, repeat={}'.format(
+        data_id, label['document'], label['prompt'], label['prompt_const_embed'],
+        label['model'], json.dumps(label['model_options']), label['repeat']))
+    if args.dry_run:
+        return
+
+    start_variation = perf_counter()
+    response = call_llm(prompt, model_config, model_options)
+
+    logger_debug_file(response['data']['text'],
+                      f'response-{variation_slug(data_id, label)}.txt')
+
+    record = {
+        'id': data_id,
+        'variation': label,
+        'llm_call': response['meta'],
+    }
+
+    # the data schema is optional: without it there is nothing to extract and
+    # validate, so the raw LLM response is stored instead
+    if schema:
+        extracted_data = extract_validate_json(response['data']['text'],
+                                               schema)
+        logger.debug('Extracted data: ' + json.dumps(extracted_data))
+        record['extraction'] = extracted_data
+    else:
+        record['response'] = response['data']['text']
+
+    record['duration_ms'] = f'{(perf_counter() - start_variation) * 1000:.0f}'
+
+    # output in output.jsonl
+    with open(os.path.join(config_module.run_dir, 'output.jsonl'), 'a') as f:
+        f.write(json.dumps(record) + '\n')
+
+    return
+
+
+def run_variations(dataset, variations: list, models: dict, schema: dict | None):
+    """Run every variation of the matrix for every record of the dataset."""
+    for data in dataset:
+        for variation in variations:
+            run_variation(data, variation, models, schema)
+
+    return
+
+
+def read_dataset(filename: str):
+    """Yield the records of a dataset file (.jsonl or .csv), detected by file extension."""
+    ext = os.path.splitext(filename)[1].lower()
+    if ext == '.csv':
+        with open(filename, 'r', newline='') as infile:
+            for record in csv.DictReader(infile):
+                if not record.get('id'):
+                    raise ValueError(f"Dataset record missing mandatory 'id' field: {record}")
+                yield record
+    else:
+        with open(filename, 'r') as infile:
+            for line in infile:
+                if not line.strip():
+                    continue
+                record = json.loads(line.strip())
+                if not record.get('id'):
+                    raise ValueError(f"Dataset record missing mandatory 'id' field: {record}")
+                yield record
+
+
+# if __name__ == "__main__":
+def cli():
+    if not args.configfile and not args.prompt and not args.prompt_filename:
+        parser.error('a prompt (direct or through prompt-filename) or a --configfile is required')
+
+    if args.configfile:
+        # Load the config file config.yaml:
+        with open(args.configfile, 'r') as file:
+            config = yaml.safe_load(file)
+        base_dir = os.path.dirname(args.configfile)
+    else:
+        config = deepcopy(config_module.config_default)
+        base_dir = os.path.expanduser(config_module.user_dir)
+
+    logs_dir = os.path.join(base_dir, 'logs')
+    runs_dir = os.path.join(base_dir, 'runs')
+    run_timestamp = datetime.now().strftime('%Y%m%d-%H%M%S')
+    config_module.log_dir = os.path.join(logs_dir, run_timestamp)
+    config_module.run_dir = os.path.join(runs_dir, run_timestamp)
+
+    os.makedirs(config_module.log_dir, exist_ok=True)
+    os.makedirs(config_module.run_dir, exist_ok=True)
+
+    # Configure logger for all (this package + dependencies).
+    logging.basicConfig(filename=os.path.join(config_module.log_dir, 'llmrunctl.log'), encoding='utf-8',
+                        level=logging.INFO,
+                        format='%(asctime)s - %(levelname)s - %(message)s',
+                        datefmt='%Y-%m-%d %H:%M:%S')
+    # Override this package's logger for level
+    if args.debug:
+        logging.getLogger('llmrunctl').setLevel(logging.DEBUG)
+
+    logger.info('Run started')
+
+    # load_dotenv()
+    # api_key = os.getenv('API_KEY')
+
+    if args.scenario not in config['scenarios']:
+        print(f"Scenario '{args.scenario}' not found in "
+              f"{args.configfile if args.configfile else 'the default config'}")
+        exit(1)
+
+    # Creating a detached/clone copy of the original data, as it will be
+    # overridden by various passed-on argument (right approach?)
+    scenario = deepcopy(config['scenarios'][args.scenario])
+    scenario_variations = scenario['variations']
+
+    if args.dataset_filename:
+        scenario['dataset'] = {'filename': args.dataset_filename}
+
+    if args.model:
+        scenario_variations['models'] = args.model.split(',')
+
+    if args.repeats is not None:
+        scenario_variations['repeats'] = args.repeats
+
+    schema_from_args = args.schema is not None or args.schema_multi is not None
+    if args.schema is not None:
+        scenario['data_schema'] = schema_dsl(args.schema)
+    if args.schema_multi is not None:
+        scenario['data_schema'] = schema_dsl(args.schema_multi, True)
+
+    # a prompt passed on the command line (text or file) replaces the whole set
+    # of variations['prompts']
+    if args.prompt_filename:
+        scenario_variations['prompts'] = [{
+            'name': 'default',
+            'template': {
+                'filename': args.prompt_filename
+            }
+        }]
+    elif args.prompt:
+        prompt_content = args.prompt
+        if schema_from_args:
+            prompt_content = build_schema_prompt(
+                args.prompt, scenario['data_schema'],
+                config_module.prompt_schema_default)
+        scenario_variations['prompts'] = [{
+            'name': 'default',
+            'template': {
+                'content': prompt_content
+            }
+        }]
+
+    if not scenario_variations.get('prompts'):
+        print('No prompt defined: pass a prompt, --prompt-filename, or define one in the config file')
+        exit(1)
+
+    # every model of the scenario must be defined in the `models` section of
+    # the config
+    model_names = scenario_variations.get('models')
+    models_config = config.get('models') or {}
+    models_undefined = [name for name in model_names if name not in models_config]
+    if models_undefined:
+        print("Model(s) {} not found in {}".format(
+            ', '.join(f"'{name}'" for name in models_undefined),
+            args.configfile if args.configfile else 'the default config'))
+        exit(1)
+
+    models = {name: deepcopy(models_config[name]) for name in model_names}
+    for model_name, model_config in models.items():
+        # the model name defaults to the key of the `models` section
+        model_config.setdefault('name', model_name)
+
+    variations = build_variations(scenario_variations)
+    print(f'Total Variations: {len(variations)} ({variations_breakdown(scenario_variations)})')
+
+    # the dataset is optional: without it a single synthetic record is used
+    dataset_config = scenario.get('dataset')
+    if dataset_config:
+        dataset_filename = dataset_config['filename']
+        dataset = list(read_dataset(dataset_filename))
+        dataset_length = len(dataset)
+        print(f'Total dataset items: {dataset_length} (in {dataset_filename})')
+    else:
+        dataset_length = 1
+        dataset = [{'id': None}]
+        print('No dataset: running the variations once')
+
+    # Iterate over the dataset and run the variations for each item:
+    start = perf_counter()
+    run_variations(dataset, variations, models, scenario.get('data_schema'))
+
+    duration_ms = (perf_counter() - start) * 1000
+
+    meta_file_content = {
+        'run_timestamp': run_timestamp,
+        'models': models,
+        'scenarios': {'default': scenario},
+        'stats': {
+            'dataset_length': dataset_length,
+            'variations_count': len(variations),
+            'llm_calls': dataset_length * len(variations),
+            'duration_ms': f'{duration_ms:.0f}',
+    }}
+    with open(os.path.join(config_module.run_dir, 'meta.json'), 'w') as f:
+        f.write(json.dumps(meta_file_content, indent=2))
+
+    print(f'Run completed in {duration_ms:.0f}ms')
+    print(f'Run output: {config_module.run_dir}')
+    logger.info(f'Run completed in {duration_ms:.0f}ms')

llmflock-0.0.2/llmflock/config.py

@@ -0,0 +1,101 @@
+"""
+Configuration for the LLM run process.
+Note: using this module as a centralized configuration point, data is modifiable.
+"""
+log_dir = '.'
+run_dir = '.' # required?
+
+# Base directory for logs/ and runs/ when the tool is used WITHOUT a config file.
+user_dir = '~/.llmrunctl'
+
+# Fallback model definition, used to synthesize a model configuration for a
+# model name that is not declared in the `models` section of the config
+# (typically `llmrunctl "<prompt>" -m <model>` without a config file).
+model_default = {
+    'backend': 'ollama_ollama',
+    'name': 'gemma3',
+    'options': {
+        'temperature': 'temperature',
+        'max_predict_tokens': 'num_predict',
+        'top_p': 'top_p',
+    }
+}
+
+# Default config used when no config.yaml file is provided: the minimal
+# scenario, stripped of every parameter that is optional. Only the prompt is
+# missing here: it is injected from the command line by `cli()`.
+config_default = {
+    'models': {
+        'gpt-oss': {
+            'backend': 'ollama_ollama',
+            'name': 'gpt-oss',
+            'options': {
+                'temperature': 'temperature',
+                'max_predict_tokens': 'num_predict',
+                'top_p': 'top_p',
+            }
+        },
+        'gemma3': {
+            'backend': 'ollama_ollama',
+            'name': 'gemma3',
+            'options': {
+                'temperature': 'temperature',
+                'max_predict_tokens': 'num_predict',
+                'top_p': 'top_p',
+            }
+        }
+    },
+    'scenarios': {
+        'default': {
+            'name': 'default scenario',
+            # dataset omitted
+            # data_schema omitted
+            'variations': {
+                # document_sets omitted
+                # prompt_const_embeds omitted
+                # prompts: populated from the command line, either as
+                # {'template': {'content': '<prompt text>'}} or
+                # {'template': {'filename': 'path/to/prompt.md'}}
+                'prompts': [],
+                'models': ['gemma3'],
+                'model_options': {
+                    # temperature omitted
+                    # top_p omitted
+                },
+                'repeats': 1
+            },
+        }
+    }
+}
+
+prompt_schema_default = '''
+# LLM Prompt
+
+## Instruction
+
+{user_prompt}
+
+## Formatting the response
+
+Format the answer in the response in JSON inside a JSON Markdown fenced code block: <human_json_schema_rules>
+
+### Examples:
+
+_example 1_:
+
+```json
+<json_example_1>
+```
+
+_example 2_:
+
+```json
+<json_example_2>
+```
+
+_example 3_:
+
+```json
+<json_example_3>
+```
+'''

llmflock-0.0.2/llmflock/ollama_ollama.py

@@ -0,0 +1,28 @@
+import logging
+import ollama
+
+logger = logging.getLogger(__name__)
+
+def ollama_ollama_call(prompt: str, model_name: str, model_options: dict) -> dict:
+    response = ollama.generate(
+        model=model_name,
+        prompt=prompt,
+        options=model_options,
+        stream=False
+    )
+    # keep all valuable response attributes except the big ones
+    meta = {k: v for k, v in vars(response).items() if k not in ['context', 'response', 'thinking']}
+    response_dict = {
+        'data': {
+            'text': response.response,
+        },
+        'meta': meta,
+    }
+    return response_dict
+
+# Test ollama server up and running:
+# curl http://localhost:11434/api/generate -d '{
+#   "model": "gemma3",
+#   "prompt": "Why is the sky blue?",
+#   "stream": false
+# }'

llmflock-0.0.2/llmflock/simonw_llm.py

@@ -0,0 +1,18 @@
+import llm
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+def simonw_llm_call(prompt: str, model_name: str, model_options: dict) -> dict:
+    # STUB
+    response_dict = {
+        'data': {
+            'text': 'BLABLABLA',
+        },
+        'meta': {
+            'var1': 1,
+            'var2': 2,
+        },
+    }
+    return response_dict

llmflock-0.0.2/llmflock.egg-info/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: llmflock
+Version: 0.0.2
+Summary: LLM Runner Control is a CLI tool to interact with local and remote LLM, define multiple scenario variations (model × prompt × options), run it over a dataset and capture structured results for comparison or to build knowledge through meta analysis.
+License-File: LICENSE.txt
+Requires-Dist: jsonschema
+Requires-Dist: llm
+Requires-Dist: llm-gpt4all
+Requires-Dist: llm-ollama
+Requires-Dist: ollama
+Requires-Dist: python-dotenv
+Requires-Dist: PyYAML
+Dynamic: license-file

llmflock-0.0.2/llmflock.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE.txt
+README.md
+pyproject.toml
+llmflock/__init__.py
+llmflock/__main__.py
+llmflock/cli.py
+llmflock/config.py
+llmflock/ollama_ollama.py
+llmflock/simonw_llm.py
+llmflock.egg-info/PKG-INFO
+llmflock.egg-info/SOURCES.txt
+llmflock.egg-info/dependency_links.txt
+llmflock.egg-info/entry_points.txt
+llmflock.egg-info/requires.txt
+llmflock.egg-info/top_level.txt

llmflock-0.0.2/llmflock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

llmflock-0.0.2/llmflock.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+llmflock = llmflock.cli:cli

llmflock-0.0.2/llmflock.egg-info/requires.txt

@@ -0,0 +1,7 @@
+jsonschema
+llm
+llm-gpt4all
+llm-ollama
+ollama
+python-dotenv
+PyYAML

llmflock-0.0.2/llmflock.egg-info/top_level.txt

@@ -0,0 +1 @@
+llmflock

llmflock-0.0.2/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "llmflock"
+version = "0.0.2"
+description = "LLM Runner Control is a CLI tool to interact with local and remote LLM, define multiple scenario variations (model × prompt × options), run it over a dataset and capture structured results for comparison or to build knowledge through meta analysis."
+dependencies = [
+    "jsonschema",
+    "llm",
+    "llm-gpt4all",
+    "llm-ollama",
+    "ollama",
+    "python-dotenv",
+    "PyYAML"
+]
+
+[project.scripts]
+llmflock = "llmflock.cli:cli"
+
+# Required to build the package since we are not using src layout
+# IE setuptools would misinterpret extra folder(s) (data) as a package if we
+# don't add this ("Multiple top-level packages discovered in a flat-layout")
+[tool.setuptools]
+packages = ["llmflock"]
+
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+
+# General note: Written using a mix of python packaging user guides,
+# simonw/llm approach and various sources from Google
+# https://packaging.python.org/en/latest/, specifically:
+# - https://packaging.python.org/en/latest/guides/creating-command-line-tools/
+# - https://packaging.python.org/en/latest/guides/writing-pyproject-toml/
+# - https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/

llmflock-0.0.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+