NAME

Chorus::Engine::AIAgent - AI agent integration for compliance-validation applications

VERSION

2.01

DESCRIPTION

Starting with version 2.01, Chorus::Engine ships an optional companion directory, agent/, that turns the inference engine into a normed-corpus compliance-validation platform when used together with an AI agent (Claude, Copilot, ECA…).

The companion provides:

Agent knowledge templates — org-mode files that capture the domain knowledge extracted from normative corpora (standards, DTUs, Eurocodes, regulations…) for each pipeline agent.
Six AI agent skills — reusable prompt-driven workflows (chorus-pdf, chorus-feed, chorus-create-project, chorus-import-project, chorus-check, chorus-strengthen) that drive an AI agent to build and run complete validation applications from a corpus.

The resulting workflow is entirely deterministic: the rules are derived from the corpus, encoded as transparent YAML files, and executed verbatim by the Chorus inference engine — no LLM in the hot path.

OVERVIEW

The architecture connects three layers:

┌──────────────────────────────────────────────────────────┐
│  Normative corpus  (PDF, DTU, Eurocode, regulation…)     │
└────────────────────────┬─────────────────────────────────┘
                         │  chorus-pdf (optional, PDF input)
                         │  chorus-feed
                         ▼
┌──────────────────────────────────────────────────────────┐
│  KB org-mode  (agent/agents/<slug>.org)                  │
│  · Frames catalogue    · Slot dictionary                 │
│  · Rules catalogue     · Perl helpers (normative tables) │
└────────────────────────┬─────────────────────────────────┘
               ┌─────────┴──────────┐
    chorus-check│                   │chorus-create-project
               ▼                   ▼
┌──────────────────────┐   ┌──────────────────────────┐
│ YAML rules           │   │ project.json             │
│ Perl helpers         │   │ (test data or real       │
│ Feed.pm / Expert.pm  │   │  engineering project)    │
│ run.pl               │   └──────────────────────────┘
└────────────┬─────────┘
             │  perl run.pl project.json
             ▼
┌──────────────────────────────────────────────────────────┐
│  Chorus::Expert pipeline                                 │
│  Agent1 → Agent2 → … → AgentN (termination)              │
└────────────────────────┬─────────────────────────────────┘
                         │
                         ▼
             Compliance report (stdout)

AI AGENT SKILLS

The skills live in agent/skills/ and are loaded on demand by the AI agent. They cover the entire lifecycle of a compliance-validation application.

chorus-pdf

chorus-pdf <sandbox-name> <file.pdf> [--out <slug>] [--auto] [--images]

Extracts a PDF corpus into a plain-text or Markdown file suitable for chorus-feed. Three extraction modes are available:

Text mode (default) — pdfminer.six, no API key required.
Auto mode (--auto) — pdfminer for text pages, LLM vision for figure and table pages. Recommended for mixed technical documents.
Images mode (--images) — LLM vision on every page. Best for scanned PDFs or diagram-heavy documents.

chorus-feed

chorus-feed <sandbox-name> <corpus> [--enrich]

Reads a normative corpus and produces all the knowledge artefacts for the sandbox:

One agent/agents/<slug>.org KB file per agent (domain, Frame catalogue, slot dictionary, rules catalogue, Perl helpers).
One YAML rules file per rule (rules/<slug>/RNN-name.yml).
One Helpers.pm per agent (normative tables, computed thresholds).
agent/agents/index.org (pipeline registry).

chorus-feed does not generate any infrastructure code (Feed.pm, Expert.pm, run.pl). Infrastructure is the sole responsibility of chorus-check.

The --enrich flag activates incremental-enrichment mode (Mode B): the existing KB is read and new corpus knowledge is merged into it. Without --enrich, the corpus is always treated as a fresh source.

chorus-create-project

chorus-create-project <sandbox-name> <output.json> [--batch]

Reads the KB org files of the sandbox and generates a project JSON file populated with both conforming and non-conforming elements that exercise all rules. The skill never reads Helpers.pm or any generated .pm file; the canonical source is always the KB org.

--batch generates the full four-file coverage suite (projet-rules-iso.json, projet-edges.json, projet-cross.json, projet-scale.json) in one pass.

chorus-import-project

chorus-import-project <sandbox-name> <source...> [--out <file.json>] [--batch]

Aligns the engineer's own project document (PDF, Word, Excel, plain text, or inline data) with the KB slot terminology and produces a valid project JSON file. Three invocation modes are supported:

Unit mode — one source file produces one JSON.
Fusion mode — N source files (same project, complementary) produce one merged JSON.
Batch mode — a directory or a glob produces one JSON per source file plus a synthesis report.

chorus-check

chorus-check <sandbox-name> <project-file.json> [--all]

The end-to-end validation command. Given a sandbox with a complete KB (the output of chorus-feed) and a project JSON file, it:

1. Detects whether the sandbox already contains generated infrastructure (run.pl, Feed.pm, Expert.pm, at least one Agent/*.pm).
2. Fast path — if the infrastructure is already present and the KB is unchanged, goes directly to execution.
3. Full path — if the infrastructure is absent or the KB has changed, generates Feed.pm, one shell Agent/*.pm per pipeline agent, Expert.pm, and run.pl from the KB, then executes the pipeline.
4. Displays the full compliance report verbatim (global rate, per-agent traversal, per-element-type breakdown, non-conformity summary).

--all runs every projet-*.json file in the sandbox and produces a synthesis table.

chorus-strengthen

chorus-strengthen <sandbox-name>

Runs the full project suite, classifies every discordance and unprocessed element into a gap type (rule too strict / too permissive / Feed gap), and produces a structured enrichment roadmap for chorus-feed --enrich. Never modifies any KB, YAML, or Perl file — read-only analysis.

KB MODEL

Each agent's knowledge is stored in a single org-mode file following the template agent/org/agents/_template.org. The template has ten sections:

* Domain               — agent speciality and corpus scope
* Targeting slots      — _SCOPE strategy + pre-population contract
* Pipeline I/O         — incoming slots (read) / outgoing slots (written)
* Ontology             — domain concepts → Frame mapping
* Frame catalogue      — per-Frame slot tables with constraints and hooks
* Slot dictionary      — flat slot reference for writing FIND/fmatch()
* Rules catalogue      — per-rule intent, FIND, CONDITION, EXCEPTION, ACTION
* Perl helpers         — normative helper signatures + full bodies
* Constraints          — domain-specific caveats and pitfalls

The pipeline registry agent/agents/index.org records all agents in pipeline order with their Perl module name, slug, KB file, and status.

SANDBOX LAYOUT

A sandbox is a self-contained directory that holds the corpus, the KB, the generated infrastructure, and the project files for one application domain:

<sandbox-name>/
  README.org              pipeline overview, corpus list, agent status
  corpus/
    001-<source>.txt      normative corpus (numbered for incremental feed)
  agent/
    agents/
      index.org           pipeline registry
      <slug>.org          per-agent KB file
  rules/
    <slug>/
      R01-<name>.yml      YAML rules (alphabetical order = load order)
      R02-<name>.yml
  lib/
    <Namespace>/
      Feed.pm             JSON → Chorus::Frame loader
      Expert.pm           pipeline assembly + process()
      Agent/
        <Name>.pm         shell: build(), loadRules(), Helpers injection
        <Name>/
          Helpers.pm      normative tables and computations
  run.pl                  entry point: Feed → Expert → report
  project-01.json         project data files

EXAMPLE

The sandbox examples/sandboxes/cob-compliance_en (included in the distribution) illustrates a full compliance pipeline for timber-frame construction (BS EN 338, EC5, Building Regulations Part L/B, BS EN 13501).

Run it without an AI agent:

perl examples/sandboxes/cob-compliance_en/run.pl \
     examples/sandboxes/cob-compliance_en/project-demo.json

A French-language version is available in examples/sandboxes/cob-compliance_fr.

WORKFLOW SUMMARY

1. chorus-pdf  <sandbox> corpus/standard.pdf --auto   (optional, PDF input)
      → corpus/001-standard-vision.md

2. chorus-feed <sandbox> corpus/001-standard-vision.md
      → KB org files  + YAML rules  + Helpers.pm

3. chorus-create-project <sandbox> project.json       (or chorus-import-project)
      → project.json  (conforming + non-conforming elements)

4. chorus-check <sandbox> project.json
      → Feed.pm  Expert.pm  Agent/*.pm  run.pl  → compliance report

# Incremental enrichment with a second corpus:
5. chorus-feed <sandbox> <second-corpus.txt> --enrich
      → updated KB + new YAML rules

# Identify rule gaps and get enrichment roadmap:
6. chorus-strengthen <sandbox>
      → gap report + corpus-correctif.txt recommendation

DESIGN PRINCIPLES

Separation of concerns — chorus-feed owns knowledge; chorus-check owns infrastructure. The two are orthogonal: a KB enrichment does not require a project, and a new project does not require re-feeding.
Full traceability — every normative threshold and table in Helpers.pm carries a # Source: §N — title annotation. Every YAML rule name maps to a section of the KB catalogue.
Deterministic execution — the AI agent participates only in the knowledge-extraction and code-generation phases. The hot path (rule firing, Frame inference, report) is pure Chorus — no LLM call at runtime.
Incremental design — a sandbox accumulates knowledge across multiple chorus-feed invocations. The generated infrastructure is always derived from the current state of the KB.

FILES

agent/skills/chorus-engine.md: Full engine reference (Frame, Engine, Expert, Collection, YAML DSL, anti-pitfalls). Loaded automatically by the AI agent when Perl code is created or modified inside the repository.
agent/skills/chorus-pdf.md: Detailed instructions for the chorus-pdf skill (extraction modes, prerequisites).
agent/skills/chorus-feed.md: Detailed instructions for the chorus-feed skill (Mode A + Mode B).
agent/skills/chorus-check.md: Detailed instructions for the chorus-check skill (fast path + full path).
agent/skills/chorus-create-project.md: Detailed instructions for the chorus-create-project skill.
agent/skills/chorus-import-project.md: Detailed instructions for the chorus-import-project skill (unit / fusion / batch modes).
agent/skills/chorus-strengthen.md: Detailed instructions for the chorus-strengthen skill (gap classification, enrichment roadmap).
agent/org/agents/_template.org: Canonical KB template for a pipeline agent (all sections).
agent/org/agents/index.org: Pipeline registry template (agent table, pipeline notes, corpus index).

AUTHOR

Christophe Ivorra, <ch.ivorra@free.fr>

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install Chorus, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Chorus

CPAN shell

perl -MCPAN -e shell
install Chorus

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	Go to GitHub issues (only if GitHub is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)