From 6137ff217be0855771dbdb492ac658d5d428ff88 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Mon, 28 Sep 2026 13:42:17 +0000 Subject: [PATCH] Migrate the standalone Audita role to version 2 configuration --- README.md | 77 ++++++++++++++++----------------- defaults/main.yml | 27 +++++------- meta/argument_specs.yml | 96 ++++++++++++++++++----------------------- templates/config.yml.j2 | 96 ++++++++++++++++------------------------- tests/integration | 29 ++++++++++--- tests/verify-config.yml | 27 +++--------- 6 files changed, 159 insertions(+), 193 deletions(-) diff --git a/README.md b/README.md index dad26e9..c2d356d 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ manage root-owned application state. ## Variables ```yaml -audita_version: v0.9.1 +audita_version: v2.0.1 audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git audita_source_dir: /usr/local/src/audita audita_binary_path: /usr/local/bin/audita @@ -20,22 +20,16 @@ audita_config_owner: root audita_config_group: root audita_config_directory_mode: "0755" audita_config_file_mode: "0644" -audita_config_version: 1 +audita_config_version: 2 +audita_profiles_dir: null +# Required caller inputs: audita_backends, audita_llm_proposal_profile audita_pipeline_modules: null audita_output_schema: null -audita_llm_proposal_base_url: null -audita_llm_proposal_model: null -audita_llm_proposal_api_key_env: null -audita_llm_proposal_timeout: null -audita_llm_proposal_max_retries: null -audita_llm_validation_base_url: null -audita_llm_validation_model: null -audita_llm_validation_api_key_env: null -audita_llm_validation_timeout: null -audita_llm_validation_max_retries: null -audita_concurrency_total_llm: null -audita_concurrency_proposal_llm: null -audita_concurrency_validation_llm: null +audita_llm_validation_profile: null +audita_llm_transient_retries: null +audita_llm_repair_attempts: null +audita_llm_operation_timeout: null +audita_validation_max_prompt_tokens: null audita_chunking_target_sections: null audita_chunking_max_section_tokens: null audita_chunking_min_section_tokens: null @@ -48,8 +42,10 @@ audita_thresholds_homophones: null audita_thresholds_spoken_word: null audita_thresholds_grammar: null audita_context_description: null +audita_reporting_enabled: null +audita_reporting_stdout_dir: null +audita_diagnostics_debug: null audita_diagnostics_work_dir: null -audita_diagnostics_retention: null ``` When `audita_manage_build_dependencies` is `false`, Git and the executable @@ -63,22 +59,23 @@ selecting `audita_version`. The role builds Audita directly to the checkout changes or the binary is absent. The source tree is recursively owned by `root:root`; the binary is `root:root` mode `0755`. -The configuration variables map directly to Audita's versioned YAML fields. -Every optional variable defaults to `null`; null values and their empty parent -sections are omitted, allowing Audita to retain ownership of its built-in +The configuration variables map directly to Audita's version-2 YAML fields. +`audita_backends` and `audita_llm_proposal_profile` are required caller inputs; +the role has no defaults for them. Callers own the selected PromptKit profile +files. Every optional variable defaults to `null`; null values and their empty +parent sections are omitted, allowing Audita to retain ownership of its built-in defaults. `audita_config_version` always renders as `version` and defaults to -`1`. The role manages `audita_config_path | dirname` and the resulting file +`2`. The role manages `audita_config_path | dirname` and the resulting file with the `audita_config_owner`, `audita_config_group`, `audita_config_directory_mode`, and `audita_config_file_mode` inputs. The standalone defaults are `root:root`, directory mode `0755`, and file mode `0644`. Composing roles may override these generic configuration inputs for their own deployment policy. -LLM API-key settings name environment variables through -`audita_llm_proposal_api_key_env` and `audita_llm_validation_api_key_env`; they -must never contain secret values. The repository-local integration suite -validates the rendered file with Audita rather than executing the CLI during -production convergence. +Backend credential references name environment variables; they must never +contain secret values. The repository-local integration suite validates the +rendered file with Audita rather than executing the CLI during production +convergence. ## Example @@ -86,25 +83,27 @@ production convergence. - hosts: audita_hosts roles: - role: ansible-role-audita + vars: + audita_backends: + local: + endpoint: http://127.0.0.1:11434/v1 + credential: null + audita_llm_proposal_profile: local-proposal ``` +The caller supplies `profiles/local-proposal.yaml` beside the managed +configuration before invoking Audita. + ## Validation The integration driver installs pinned collection dependencies, runs syntax -checking and ansible-lint, and validates the default configuration with Audita -before requiring clean repeated convergence. It also covers one representative -field-specific configuration with nested values, null omission, and intentional -falsey values, then validates it natively. A combined recovery scenario proves -that a missing binary is rebuilt with a caller-supplied Go executable while -dependency management is disabled. Audita currently has no native -release-identity command, so the suite intentionally does not use a source -commit as a version-test proxy. -On a fresh host, default convergence may also install Git through APT, refresh -the APT cache, and install the Go Snap. Application state is limited to -`/usr/local/src/audita`, `/usr/local/bin/audita`, and -`/usr/local/etc/audita/config.yml`; temporary test-specific files remain inside -the suite's private temporary directory. The suite restores the default -deployment during cleanup: +checking and ansible-lint, validates a caller-supplied local configuration and +profile offline, and requires clean repeated convergence. It also tests a +caller-supplied Go executable with dependency management disabled after removing +the managed binary. On a fresh host, the role may install Git through APT and +the Go Snap. The test uses a private temporary configuration and profile root; +the role still manages the local source checkout and binary. Cleanup removes +only the private fixture root: ```sh tests/integration diff --git a/defaults/main.yml b/defaults/main.yml index 735b77f..2152b6d 100644 --- a/defaults/main.yml +++ b/defaults/main.yml @@ -1,5 +1,5 @@ --- -audita_version: v0.9.1 +audita_version: v2.0.1 audita_repository_url: https://gitea.maximumdirect.net/eric/audita.git audita_source_dir: /usr/local/src/audita audita_binary_path: /usr/local/bin/audita @@ -11,22 +11,15 @@ audita_config_owner: root audita_config_group: root audita_config_directory_mode: "0755" audita_config_file_mode: "0644" -audita_config_version: 1 +audita_config_version: 2 +audita_profiles_dir: null audita_pipeline_modules: null audita_output_schema: null -audita_llm_proposal_base_url: null -audita_llm_proposal_model: null -audita_llm_proposal_api_key_env: null -audita_llm_proposal_timeout: null -audita_llm_proposal_max_retries: null -audita_llm_validation_base_url: null -audita_llm_validation_model: null -audita_llm_validation_api_key_env: null -audita_llm_validation_timeout: null -audita_llm_validation_max_retries: null -audita_concurrency_total_llm: null -audita_concurrency_proposal_llm: null -audita_concurrency_validation_llm: null +audita_llm_validation_profile: null +audita_llm_transient_retries: null +audita_llm_repair_attempts: null +audita_llm_operation_timeout: null +audita_validation_max_prompt_tokens: null audita_chunking_target_sections: null audita_chunking_max_section_tokens: null audita_chunking_min_section_tokens: null @@ -39,5 +32,7 @@ audita_thresholds_homophones: null audita_thresholds_spoken_word: null audita_thresholds_grammar: null audita_context_description: null +audita_reporting_enabled: null +audita_reporting_stdout_dir: null +audita_diagnostics_debug: null audita_diagnostics_work_dir: null -audita_diagnostics_retention: null diff --git a/meta/argument_specs.yml b/meta/argument_specs.yml index a861623..d5e0028 100644 --- a/meta/argument_specs.yml +++ b/meta/argument_specs.yml @@ -55,6 +55,14 @@ argument_specs: type: int required: true description: Version of the Audita configuration schema. + audita_profiles_dir: + type: path + required: false + description: Optional caller-managed PromptKit profile directory. + audita_backends: + type: dict + required: true + description: Native backend mapping supplied by the caller. audita_pipeline_modules: type: list elements: str @@ -64,58 +72,30 @@ argument_specs: type: str required: false description: Optional output schema. - audita_llm_proposal_base_url: + audita_llm_proposal_profile: + type: str + required: true + description: Caller-selected proposal PromptKit profile ID. + audita_llm_validation_profile: type: str required: false - description: Optional proposal LLM base URL. - audita_llm_proposal_model: - type: str - required: false - description: Optional proposal LLM model. - audita_llm_proposal_api_key_env: - type: str - required: false - description: Optional proposal LLM API key environment variable name. - audita_llm_proposal_timeout: - type: raw - required: false - description: Optional proposal LLM timeout in seconds or duration form. - audita_llm_proposal_max_retries: + description: Optional validation PromptKit profile ID; omission inherits proposal. + audita_llm_transient_retries: type: int required: false - description: Optional proposal LLM retry count. - audita_llm_validation_base_url: + description: Optional additional transient attempts per generation. + audita_llm_repair_attempts: + type: int + required: false + description: Optional additional structural repair generations. + audita_llm_operation_timeout: type: str required: false - description: Optional validation LLM base URL. - audita_llm_validation_model: - type: str - required: false - description: Optional validation LLM model. - audita_llm_validation_api_key_env: - type: str - required: false - description: Optional validation LLM API key environment variable name. - audita_llm_validation_timeout: - type: raw - required: false - description: Optional validation LLM timeout in seconds or duration form. - audita_llm_validation_max_retries: + description: Optional logical-operation deadline as a Go duration. + audita_validation_max_prompt_tokens: type: int required: false - description: Optional validation LLM retry count. - audita_concurrency_total_llm: - type: int - required: false - description: Optional total LLM concurrency. - audita_concurrency_proposal_llm: - type: int - required: false - description: Optional proposal LLM concurrency. - audita_concurrency_validation_llm: - type: int - required: false - description: Optional validation LLM concurrency. + description: Optional validation batching token budget. audita_chunking_target_sections: type: int required: false @@ -129,17 +109,17 @@ argument_specs: required: false description: Optional minimum section token count. audita_normalization_max_segment_gap: - type: raw + type: float required: false - description: Optional maximum segment gap in seconds or duration form. + description: Optional maximum segment gap in numeric seconds. audita_normalization_ellipsis_gap: - type: raw + type: float required: false - description: Optional ellipsis gap in seconds or duration form. + description: Optional ellipsis gap in numeric seconds. audita_normalization_max_segment_duration: - type: raw + type: float required: false - description: Optional maximum segment duration in seconds or duration form. + description: Optional maximum segment duration in numeric seconds. audita_normalization_max_segment_tokens: type: int required: false @@ -164,11 +144,19 @@ argument_specs: type: str required: false description: Optional transcript context description. + audita_reporting_enabled: + type: bool + required: false + description: Optional ordinary report-bundle policy. + audita_reporting_stdout_dir: + type: str + required: false + description: Optional report directory for stdout output. + audita_diagnostics_debug: + type: bool + required: false + description: Optional detailed debug-artifact policy. audita_diagnostics_work_dir: type: str required: false description: Optional diagnostics work directory. - audita_diagnostics_retention: - type: str - required: false - description: Optional diagnostics retention policy. diff --git a/templates/config.yml.j2 b/templates/config.yml.j2 index f9427d0..01fa006 100644 --- a/templates/config.yml.j2 +++ b/templates/config.yml.j2 @@ -1,4 +1,22 @@ -version: {{ audita_config_version }} +version: {{ audita_config_version | to_json }} +{% if audita_profiles_dir is not none %} +profiles_dir: {{ audita_profiles_dir | to_json }} +{% endif %} +backends: {{ audita_backends | to_json }} +llm: + proposal_profile: {{ audita_llm_proposal_profile | to_json }} +{% if audita_llm_validation_profile is not none %} + validation_profile: {{ audita_llm_validation_profile | to_json }} +{% endif %} +{% if audita_llm_transient_retries is not none %} + transient_retries: {{ audita_llm_transient_retries | to_json }} +{% endif %} +{% if audita_llm_repair_attempts is not none %} + repair_attempts: {{ audita_llm_repair_attempts | to_json }} +{% endif %} +{% if audita_llm_operation_timeout is not none %} + operation_timeout: {{ audita_llm_operation_timeout | to_json }} +{% endif %} {% if audita_pipeline_modules is not none %} pipeline: modules: {{ audita_pipeline_modules | to_json }} @@ -7,56 +25,9 @@ pipeline: output: schema: {{ audita_output_schema | to_json }} {% endif %} -{% if audita_llm_proposal_base_url is not none or audita_llm_proposal_model is not none or audita_llm_proposal_api_key_env is not none or audita_llm_proposal_timeout is not none or audita_llm_proposal_max_retries is not none or audita_llm_validation_base_url is not none or audita_llm_validation_model is not none or audita_llm_validation_api_key_env is not none or audita_llm_validation_timeout is not none or audita_llm_validation_max_retries is not none %} -llm: -{% if audita_llm_proposal_base_url is not none or audita_llm_proposal_model is not none or audita_llm_proposal_api_key_env is not none or audita_llm_proposal_timeout is not none or audita_llm_proposal_max_retries is not none %} - proposal: -{% if audita_llm_proposal_base_url is not none %} - base_url: {{ audita_llm_proposal_base_url | to_json }} -{% endif %} -{% if audita_llm_proposal_model is not none %} - model: {{ audita_llm_proposal_model | to_json }} -{% endif %} -{% if audita_llm_proposal_api_key_env is not none %} - api_key_env: {{ audita_llm_proposal_api_key_env | to_json }} -{% endif %} -{% if audita_llm_proposal_timeout is not none %} - timeout: {{ audita_llm_proposal_timeout | to_json }} -{% endif %} -{% if audita_llm_proposal_max_retries is not none %} - max_retries: {{ audita_llm_proposal_max_retries | to_json }} -{% endif %} -{% endif %} -{% if audita_llm_validation_base_url is not none or audita_llm_validation_model is not none or audita_llm_validation_api_key_env is not none or audita_llm_validation_timeout is not none or audita_llm_validation_max_retries is not none %} - validation: -{% if audita_llm_validation_base_url is not none %} - base_url: {{ audita_llm_validation_base_url | to_json }} -{% endif %} -{% if audita_llm_validation_model is not none %} - model: {{ audita_llm_validation_model | to_json }} -{% endif %} -{% if audita_llm_validation_api_key_env is not none %} - api_key_env: {{ audita_llm_validation_api_key_env | to_json }} -{% endif %} -{% if audita_llm_validation_timeout is not none %} - timeout: {{ audita_llm_validation_timeout | to_json }} -{% endif %} -{% if audita_llm_validation_max_retries is not none %} - max_retries: {{ audita_llm_validation_max_retries | to_json }} -{% endif %} -{% endif %} -{% endif %} -{% if audita_concurrency_total_llm is not none or audita_concurrency_proposal_llm is not none or audita_concurrency_validation_llm is not none %} -concurrency: -{% if audita_concurrency_total_llm is not none %} - total_llm: {{ audita_concurrency_total_llm | to_json }} -{% endif %} -{% if audita_concurrency_proposal_llm is not none %} - proposal_llm: {{ audita_concurrency_proposal_llm | to_json }} -{% endif %} -{% if audita_concurrency_validation_llm is not none %} - validation_llm: {{ audita_concurrency_validation_llm | to_json }} -{% endif %} +{% if audita_validation_max_prompt_tokens is not none %} +validation: + max_prompt_tokens: {{ audita_validation_max_prompt_tokens | to_json }} {% endif %} {% if audita_chunking_target_sections is not none or audita_chunking_max_section_tokens is not none or audita_chunking_min_section_tokens is not none %} chunking: @@ -73,13 +44,13 @@ chunking: {% if audita_normalization_max_segment_gap is not none or audita_normalization_ellipsis_gap is not none or audita_normalization_max_segment_duration is not none or audita_normalization_max_segment_tokens is not none %} normalization: {% if audita_normalization_max_segment_gap is not none %} - max_segment_gap: {{ audita_normalization_max_segment_gap | to_json }} + max_segment_gap: {{ audita_normalization_max_segment_gap | float | to_json }} {% endif %} {% if audita_normalization_ellipsis_gap is not none %} - ellipsis_gap: {{ audita_normalization_ellipsis_gap | to_json }} + ellipsis_gap: {{ audita_normalization_ellipsis_gap | float | to_json }} {% endif %} {% if audita_normalization_max_segment_duration is not none %} - max_segment_duration: {{ audita_normalization_max_segment_duration | to_json }} + max_segment_duration: {{ audita_normalization_max_segment_duration | float | to_json }} {% endif %} {% if audita_normalization_max_segment_tokens is not none %} max_segment_tokens: {{ audita_normalization_max_segment_tokens | to_json }} @@ -104,12 +75,21 @@ thresholds: context: description: {{ audita_context_description | to_json }} {% endif %} -{% if audita_diagnostics_work_dir is not none or audita_diagnostics_retention is not none %} +{% if audita_reporting_enabled is not none or audita_reporting_stdout_dir is not none %} +reporting: +{% if audita_reporting_enabled is not none %} + enabled: {{ audita_reporting_enabled | to_json }} +{% endif %} +{% if audita_reporting_stdout_dir is not none %} + stdout_dir: {{ audita_reporting_stdout_dir | to_json }} +{% endif %} +{% endif %} +{% if audita_diagnostics_debug is not none or audita_diagnostics_work_dir is not none %} diagnostics: +{% if audita_diagnostics_debug is not none %} + debug: {{ audita_diagnostics_debug | to_json }} +{% endif %} {% if audita_diagnostics_work_dir is not none %} work_dir: {{ audita_diagnostics_work_dir | to_json }} {% endif %} -{% if audita_diagnostics_retention is not none %} - retention: {{ audita_diagnostics_retention | to_json }} -{% endif %} {% endif %} diff --git a/tests/integration b/tests/integration index a4be11a..67d5bbd 100755 --- a/tests/integration +++ b/tests/integration @@ -14,12 +14,13 @@ converge="$repository_root/tests/converge.yml" verify_config="$repository_root/tests/verify-config.yml" ansible_playbook="$workspace_venv/bin/ansible-playbook" binary_path=/usr/local/bin/audita -config_path=/usr/local/etc/audita/config.yml +config_root="$test_tmp/config" +config_path="$config_root/config.yml" +profile_dir="$config_root/profiles" cleanup() { exit_status=$? trap - EXIT - "$ansible_playbook" -i "$inventory" "$converge" >/dev/null 2>&1 || true rm -rf -- "$test_tmp" exit "$exit_status" } @@ -32,31 +33,47 @@ require_clean_recap() { run_converge() { output_file=$1 shift - "$ansible_playbook" -i "$inventory" "$@" "$converge" | tee "$output_file" + "$ansible_playbook" -i "$inventory" "${baseline_args[@]}" "$@" "$converge" | tee "$output_file" } validate_config() { "$binary_path" config validate --config "$config_path" } +mkdir -p "$profile_dir" +printf '%s\n' \ + 'id: fixture-proposal' \ + 'backend: fixture' \ + 'model: offline-fixture' \ + 'timeout_seconds: 30' > "$profile_dir/fixture-proposal.yaml" + +baseline_args=( + -e "audita_config_path=$config_path" + -e "audita_config_owner=$(id -un)" + -e "audita_config_group=$(id -gn)" + -e '{"audita_backends": {"fixture": {"endpoint": "http://127.0.0.1:11434/v1", "credential": null}}, "audita_llm_proposal_profile": "fixture-proposal"}' +) + cd "$repository_root" "$workspace_venv/bin/ansible-galaxy" collection install \ -r collections/requirements.yml \ -p "$ANSIBLE_COLLECTIONS_PATH" -"$ansible_playbook" -i "$inventory" --syntax-check "$converge" +"$ansible_playbook" -i "$inventory" "${baseline_args[@]}" --syntax-check "$converge" "$workspace_venv/bin/ansible-lint" "$converge" "$verify_config" baseline_log="$test_tmp/baseline.log" run_converge "$baseline_log" validate_config +"$binary_path" config print-effective --config "$config_path" --view profiles > "$test_tmp/baseline-profiles.yml" baseline_repeat_log="$test_tmp/baseline-repeat.log" run_converge "$baseline_repeat_log" require_clean_recap "$baseline_repeat_log" -representative_config='{"audita_config_version": 1, "audita_pipeline_modules": ["glossary"], "audita_llm_proposal_base_url": "https://openrouter.ai/api/v1", "audita_llm_proposal_model": "openrouter/google/gemma-4-31b-it", "audita_llm_proposal_timeout": "10s", "audita_llm_proposal_max_retries": 0, "audita_context_description": "", "audita_diagnostics_retention": "never", "audita_llm_validation_model": null, "audita_output_schema": null, "audita_diagnostics_work_dir": null}' +representative_config='{"audita_pipeline_modules": ["glossary"], "audita_context_description": "", "audita_output_schema": null, "audita_llm_validation_profile": null}' representative_log="$test_tmp/representative-config.log" run_converge "$representative_log" -e "$representative_config" -"$ansible_playbook" -i "$inventory" "$verify_config" +validate_config +"$ansible_playbook" -i "$inventory" -e "audita_test_config_path=$config_path" "$verify_config" representative_repeat_log="$test_tmp/representative-config-repeat.log" run_converge "$representative_repeat_log" -e "$representative_config" require_clean_recap "$representative_repeat_log" diff --git a/tests/verify-config.yml b/tests/verify-config.yml index ab5240e..d1fc9e8 100644 --- a/tests/verify-config.yml +++ b/tests/verify-config.yml @@ -4,34 +4,21 @@ gather_facts: false tasks: - name: Read rendered configuration - become: true ansible.builtin.slurp: - src: /usr/local/etc/audita/config.yml + src: "{{ audita_test_config_path }}" register: audita_rendered_config_file - name: Check representative rendered configuration ansible.builtin.assert: that: - - audita_rendered_config.version == 1 + - audita_rendered_config.version == 2 + - audita_rendered_config.backends.fixture.endpoint == "http://127.0.0.1:11434/v1" + - audita_rendered_config.backends.fixture.credential is none + - audita_rendered_config.llm.proposal_profile == "fixture-proposal" - audita_rendered_config.pipeline.modules == ["glossary"] - - audita_rendered_config.llm.proposal.base_url == "https://openrouter.ai/api/v1" - - audita_rendered_config.llm.proposal.model == "openrouter/google/gemma-4-31b-it" - - audita_rendered_config.llm.proposal.timeout == "10s" - - audita_rendered_config.llm.proposal.max_retries == 0 - audita_rendered_config.context.description == "" - - audita_rendered_config.diagnostics.retention == "never" - - audita_rendered_config.llm.validation is not defined + - audita_rendered_config.llm.validation_profile is not defined - audita_rendered_config.output is not defined - - audita_rendered_config.diagnostics.work_dir is not defined + - audita_rendered_config.diagnostics is not defined vars: audita_rendered_config: "{{ audita_rendered_config_file.content | b64decode | from_yaml }}" - - - name: Validate rendered configuration - ansible.builtin.command: - argv: - - /usr/local/bin/audita - - config - - validate - - --config - - /usr/local/etc/audita/config.yml - changed_when: false