API documentation¶

Classify each governance requirement as AUTOMATED, PARTIAL, or MANUAL based on pipeline controls from pipeline_control_mappings.yaml.

Parameters:

• manifest (PolicyManifest) –

  description

• nexus (_type_) –

  description

Returns:

• ComplianceSummary ( ComplianceSummary ) –

  description

Classify skill sensitivity from tool list and body keywords.

── Tool sensitivity classification ───────────────────────────────¶

¶

Simple lookup: tool name → sensitivity tier + operation types.¶

Grounded in POSIX permission model (R/W/X) and Google OAuth¶

3-tier sensitivity (non-sensitive / sensitive / restricted).¶

¶

PROVENANCE: claude-suggested — validate tool classifications¶

Returns: tier, operations, and body-detected capabilities.

Risk Analysis and Policy Generation Pipeline for Mellea skill

Parameters:

• skill_name (str) –

  Mellea Skill spec path.

• dry_run (bool, default: False ) –

  Preview without making LLM calls. Defaults to False.

• model (Optional[str], default: None ) –

  Model to use for Risk and Action Identification. The inference_engine param must support the model. If set to None, the default model for the inference engine will be used.

• inference_engine (InferenceEngineType, default: OLLAMA ) –

  Service to use for LLM inference. Defaults to InferenceEngineType.OLLAMA.

Identify applicable risks and governance actions to produce a multi-taxonomy policy manifest.

Parameters:

• use_case (str) –

  Natural language description of the agent's purpose.

• nexus (AIAtlasNexus) –

  AI Atlas Nexus instance.

• model (Optional[str], default: None ) –

  Model to use for Risk and Action Identification. The inference_engine param must support the model. If set to None, the default model for the inference engine will be used.

• inference_engine (InferenceEngineType, default: OLLAMA ) –

  Service to use for LLM inference. Defaults to InferenceEngineType.OLLAMA.

• governance_taxonomies (Optional[list[str]], default: None ) –

  List of taxonomy IDs for governance actions.

Returns: PolicyManifest with Guardian risks and governance actions.

Generate a human-readable .md policy document from a manifest.

Search for policy_manifest.json in standard locations.

Checks the skill root first (portable), then the audit directory.

Full Certification Pipeline for Mellea skill

Parameters:

• pipeline_dir (Path) –

  Compiled Mellea skill pipeline directory.

• fixture_id (Optional[str], default: None ) –

  Specify a fixture to run with the certification process. Defaults to None.

• enforce (bool, default: False ) –

  Run pipeline in enforce mode (block on risk detection). Defaults to False.

• model (Optional[str], default: None ) –

  Model to use for Risk and Action Identification. The inference_engine param must support the model. If set to None, the default model for the inference engine will be used.

• guardian_model (Optional[str], default: None ) –

  Model to use for Risk Assessment. The inference_engine param must support the model. If set to None, the default guardian model for the inference engine will be used.

• inference_engine (InferenceEngineType, default: OLLAMA ) –

  Service to use for LLM inference. Defaults to InferenceEngineType.OLLAMA.

Generate a Markdown certification report with evidence.

Parameters:

• manifest (PolicyManifest) –

  description

• compliance (ComplianceSummary) –

  description

• audit_trail (list[dict]) –

  description

• audit_path (str, default: '' ) –

  description. Defaults to "".

Returns:

• str ( str ) –

  description

Load JSONL audit trail into a list of dicts.

Assemble the instruction string passed to the mellea-fy slash command.

Combines the existing autonomous-run directive with the resolved backend and model_id values, plus a notice listing the paths the wrapper renders authoritatively from JSON (the LLM cannot Write/Edit them — denied via --settings). This tells the LLM to emit the IR JSON instead of trying to write the rendered source itself, so the first attempt is correct rather than denied-then-retried.

package_name is the wrapper-derived Rule OUT-2 name (e.g. weather_mellea) substituted into the prompt body so the LLM uses the same name the wrapper computes for mirror_companion_dirs and the post-session *_mellea discovery. Previously the prompt carried the literal placeholder <package_name> and the LLM re-derived the name from the frontmatter — a long/complex name (e.g. gdpr-breach-sentinel-oliver-schmidt-prietz) could be mis-transcribed and produce a stray sibling directory.

Apply Rule OUT-2 (lowercase, hyphens/spaces → underscores, append _mellea).

For .md sources, prefer the frontmatter name: field; fall back to the parent directory name. For directory inputs (multi-file runtimes), use the directory name.

Rule OUT-6 — mirror companion directories from skill root into the package.

Runs deterministically before mellea-fy so the LLM sees the mirrored assets in / when it generates code, reinforcing the package-relative path-resolution invariant. Returns the list of directory names actually mirrored (for logging).

Pick the backend and model_id to bake into the compiled skill.

Precedence: CLI overrides win, then the defaults file, then a built-in fallback if the file is missing or unreadable. Returns (backend, model_id, source) where source records where the values came from for the compile log.

Write a per-invocation Claude Code --settings file with the deny rules.

Path-scoped Write/Edit denies prevent the LLM from clobbering files the wrapper will render after the slash command exits. acceptEdits permission mode does NOT override deny — Anthropic's evaluation order is deny → mode → allow (verified end-to-end in the synthetic deny-rule test).

Important: the deny rule paths must match what the LLM actually tries to write. Claude Code interprets relative paths against the subprocess cwd (the user's shell cwd, typically the repo root). So the deny path must be the full path-from-cwd to the package, not just the bare package name. Earlier versions used package_name/<rel>, which mis-scoped the deny to <cwd>/<package_name>/<rel> and confused the LLM into creating the package at the wrong location.

Save the chosen backend and model_id alongside the package.

The post-compile lint reads this file to confirm the generated config.py actually used these values (and didn't drift from what we instructed).

Write mellea_api_ref.json to intermediate_dir.

Cached by installed mellea version under ~/.cache/mellea-skills-compiler/api_ref_<version>.json. If mellea is not installed, writes the grounding_unavailable: true shape and returns.

Write mellea_doc_index.json to intermediate_dir.

Cached at ~/.cache/mellea-skills-compiler/doc_index.json with a ttl_hours TTL (default 24h). On fetch failure, reuses a stale cache if one exists; otherwise writes the static 2026-04-28 fallback list.

Reject any path-join construction that resolves a bundled-asset path via anything other than Path(__file__).parent.

Fixture inputs must not pass bare dicts where run_pipeline expects Pydantic models.

<package>/fixtures/__init__.py must export ALL_FIXTURES or FIXTURES.

m.instruct(...) calls whose result is parsed must include format=.

Every grounding_context= dict-literal value should be a string.

No module-level Calls outside the documented allowlist.

Bare ast.Expr whose value is a Call (e.g. load_dotenv() at the top of a file) executes at import time; flagged. Module-level assignments where the RHS is a Call are flagged only when the callee is known to be side-effecting (network/env mutation) — allowing safe patterns like LOGGER = logging.getLogger(__name__).

Every mellea.* import path must exist in mellea_api_ref.json:.modules.

KB1: m.instruct(format=Model) returns a thunk, not a Pydantic model.

The thunk MUST be parsed before any field access. Exempt patterns: - _parse_instruct_result(thunk, M) - _safe_parse_with_fallback(thunk, M, **defaults) - M.model_validate_json(thunk.value)

Every .py file under the package must parse, and <pkg>.pipeline must import.

Two checks, executed in order:

1. Per-file parseability: ast.parse(p.read_text()) for every .py file directly under <package_dir>/ and <package_dir>/fixtures/.
2. Package importability: python -c "import <package_name>.pipeline" executed as a clean subprocess from <package_dir>.parent. This surfaces wrong external import paths (e.g. mellea.stdlib.strategies instead of mellea.stdlib.sampling) that ast.parse() cannot detect.

Why a subprocess: importing the package directly in the lint process would pollute namespace, risk hanging on import side effects, or get masked by cached sys.modules entries. A clean child process surfaces exactly the error a downstream consumer (pip install + python -c) would see.

Missing pipeline.py: returns one ERROR failure naming the absent entry module. Tier 1 should hard-fail loudly so the slash-command gate halts before Tier ⅔ lints run on a package with no entry.

Scope: files directly under <package_dir>/ and <package_dir>/fixtures/ only.

m.instruct(prefix=<config_constant>) is misuse (KB7).

prefix= is for structured-output continuation; not for persona / system-prompt injection.

The compiled config.py must use the backend and model_id we instructed.

Compares the BACKEND and MODEL_ID constants in /config.py against the values recorded at /intermediate/runtime_directive.json (which captures what the compile pipeline injected via the system prompt). If the LLM ignored the directive and emitted different values, this fails loudly.

Skipped when the directive file is absent — usually because the package was compiled with an older pipeline that did not write the directive.

Each start_session(...) block must use at most one distinct format type.

MelleaSession method calls must supply required positional arguments.

Flag clearly-non-dict arguments passed to Mellea API grounding_context= kwargs.

Narrow MVP scope: only checks grounding_context= on session-method calls in the instruct/chat/act family.

Reject any direct call to <req>.validation_fn(...) in generated code.

Run all implemented Step 7 structural lints; write step_7_report.json.

Shared implementation for the validate command and the compile auto-chain.

Execute one (or all) fixtures and write step_7b_report.json.

Parameters:

• package_dir (Path) –

  compiled package directory (e.g. <skill>/<name>_mellea).

• all_fixtures (bool, default: False ) –

  if False (default), only the first fixture in ALL_FIXTURES is executed. If True, every fixture is run sequentially.

Read and validate melleafy.json. Returns raw manifest dict.

Parse manifest fields, derive entry point, detect policy manifest.

Build TranslationPlan from LoadedContext. Dispatches to target module.

Write all files. Uses .partial/ pattern for atomic write.

Basic structural lint on emitted files. Halts with exit code 4 on failure.