Skip to content

Pack and AI

NetOrca Pack is the platform's AI automation engine: instead of you writing the rendering logic of a service, per-service AI processors turn consumer declarations into ready-to-deploy configuration, verify it, and hand it to an executor - yours, or the platform's. This page maps the Pack concepts onto the collection's modules; the end-to-end story with final playbooks is the AI-operated service scenario.

The object model

graph LR
    LLM["LLM model<br/>(platform catalogue)"] --> P["AI processor<br/>action_type: config / verify /<br/>execution / optimiser / validator"]
    P --> S[Service]
    D["Documents<br/>(knowledge)"] -->|RAG retrieval| P
    PROF["Pack profile<br/>pack_enabled + retrieval tuning"] --> S
    SI[Service item] -->|approval / trigger| PIPE["Pack pipeline<br/>config -> verify -> execution"]
    P -->|runs the stages| PIPE
    EX["Your executor"] -->|pack data push| PIPE
    PIPE -->|applied| EX
Concept What it is Read with Manage with
LLM model Provider + model + pricing + credentials, configured platform-wide by an admin netorca_llm_model_info GUI only (see below)
AI processor The per-service AI agent for one action_type netorca_ai_processor_info netorca_ai_processor
Pack profile Per-service master switch + retrieval tuning netorca_pack_profile_info netorca_pack_profile
Document Per-service knowledge text retrieved into prompts netorca_ai_document_info netorca_ai_document
Pack pipeline One recorded run through the stages netorca_pack_pipeline_info netorca_pack_pipeline (applied only)
Pack data One stage's payload within a run netorca_pack_data_info netorca_pack_data (push)
Trigger / retrigger Start or restart a run - netorca_pack_trigger

The pipeline lifecycle

A pipeline is created every time a service item's processors run. Its state is WAITING_FOR_RESPONSE while a stage is running (or waiting for your executor), then OK or FAILED; version increments per run, current_stage names where it stands, and cost accumulates the LLM spend of the run. Stages auto-advance: config output feeds verify, and verify feeds execution.

Runs start four ways:

  1. A change instance is approved - the platform triggers the pipeline itself. This is the production path; with allow_auto_approval on a change_instance_validator processor, the whole flow from consumer request to rendered config can be zero-touch.
  2. A validator fires when a consumer's change arrives in PENDING.
  3. Manually with netorca_pack_trigger - re-renders, scheduled runs, demos.
  4. Retrigger (retrigger: true) - restarts the run from config, optionally carrying your comment into the prompts. This is the self-healing loop after a failed deployment.

Every run costs money

Each trigger invokes the service's LLM; the pipeline's cost field shows what a run cost. Guard trigger loops with when: conditions, and prefer polling (netorca_pack_pipeline_info) over re-triggering.

The executor loop

If the service's execution stage is external (no platform universal executor), the pipeline stops at WAITING_FOR_RESPONSE / current_stage: execution until your automation answers. The loop:

- name: Work queue - successful runs not yet applied
  netautomate.netorca.netorca_pack_pipeline_info:
    state: [OK]
    applied: false
  register: queue

# deploy queue.pack_pipelines[*].config.data with your infra role, then per pipeline:

- name: Report the execution result into the run
  netautomate.netorca.netorca_pack_data:
    object_id: "{{ pipeline.config.object_id }}"
    stage: execution
    data: {success: true, deployed_at: "{{ now(utc=true).isoformat() }}"}

- name: Take the run off the queue
  netautomate.netorca.netorca_pack_pipeline:
    id: "{{ pipeline.id }}"
    applied: true

On failure, report success: false with the error - and let netorca_pack_trigger with retrigger: true + comment ask the AI to fix its own rendering. The full version, with gating and block/rescue, is examples/scenarios/pack_ai/executor_loop.yml.

Knowledge and retrieval (RAG)

Processors with enable_pack_context retrieve the service's documents into their prompts. netorca_ai_document keeps documents in sync with files in your repository (content is compared verbatim - a plain loop is idempotent), and netorca_pack_profile tunes how they are chunked, embedded and selected (top_k, cosine_similarity_threshold, max_chars, ...). The profile also carries the master switch: pack_enabled is what turns Pack on for a service.

Permissions, secrets and platform boundaries

  • LLM model writes are GUI-only. The platform accepts LLM model creation, updates, deletion and connection tests exclusively from superuser GUI sessions - API keys are rejected outright - so the collection ships netorca_llm_model_info and deliberately no write module. Configure models once in Platform Settings, then reference them by ID from processors.
  • Provider credentials never reach playbooks. Every extra_data value in LLM model results is returned as REDACTED (keys stay visible); the platform additionally masks api_key server-side.
  • Processor extra_data is not secret - it holds behaviour switches, and the module merges your keys over the current values so omitted switches are never reset.
  • Everything else follows the collection's normal authentication and error handling: pack endpoints are team-scoped, and a 403 means the API key's team does not own the service.

Poll, don't busy-wait

The versions view is the cheap way to notice a new run; latest fetches only the newest pipeline. A trigger-then-wait looks like:

- netautomate.netorca.netorca_pack_trigger:
    object_id: 389
    stage: config

- netautomate.netorca.netorca_pack_pipeline_info:
    latest: true
    object_id: 389
  register: run
  until: run.count == 1 and run.pack_pipelines[0].state in ['OK', 'FAILED']
  retries: 20
  delay: 15