add-rules

Add Rules

Goal

Use POST /api/v1/rules/compile to compile user-authorized durable constraints into OpenViking Rules, then verify the task result and saved Rules.

Workflow

1. Identify the user's rule text or policy sources and the intended OpenViking connection. Use the same instance and identity for upload, compilation, task polling, and verification.

2. Choose exactly one invocation mode for the entire workflow:

   • Python SDK mode: use when the Agent runs in Python and the OpenViking SDK is available. Use SDK methods for source upload, compilation, task polling, and reading.
   • HTTP mode: use for other languages or general-purpose Agents. Use HTTP endpoints for source upload, compilation, task polling, and reading. Do not mix SDK calls and direct HTTP calls within one compilation workflow.

3. Build a request with top-level instruction and sources; at least one must be non-empty. Preserve the source's obligations, applicability conditions, exceptions, thresholds, and identifiers without inventing policy.

4. Continue only with the selected mode and use its exact parameter shape:

   Python SDK mode

   options supports sources. Each source may be a local file or directory path, a remote URL, a Resource URI, or an advanced source dictionary. The SDK uploads local paths automatically.

   task = client.rule_compile(
       instruction="Compile the supplied policy into durable Rules.",
       options={
           "sources": [
               "/local/path/policy.md",
               "https://example.org/policy.md",
               "viking://resources/team-policy",
           ]
       },
   )
   task_id = task["task_id"]
   

   Poll with client.get_task(task_id) and read saved content with client.read_raw(uri).

   HTTP mode

   HTTP has no options wrapper. Put instruction and sources directly in the JSON body. Use resource_uri for an existing Resource, path for a remote text source, or temp_file_id returned by POST /api/v1/resources/temp_upload for local content.

   {
     "instruction": "Compile the supplied policy into durable Rules.",
     "sources": [
       {"resource_uri": "viking://resources/team-policy"},
       {"path": "https://example.org/policy.md"},
       {"temp_file_id": "tmp_xxx", "source_name": "policy.md"}
     ]
   }
   

   Submit this body to POST /api/v1/rules/compile. Never send a client-local path to that endpoint. Poll GET /api/v1/tasks/{task_id} and read saved content through GET /api/v1/content/read?uri=...&raw=true.

   Save the returned task_id; acceptance does not mean compilation has completed.

5. Poll using the selected mode until the task is completed, failed, or cancelled. Query the existing task rather than resubmitting the request.

6. Inspect result.operations, written_uris, and write_result. Distinguish saved Rules from NOOP, UNCERTAIN, and REJECT results; completed does not guarantee new Rules.

7. Read representative saved Rules and their Scenarios using the selected mode. Check the policy text and evidence, and verify rules/<scenario_id>/abstract.md holds Scenario metadata while Rule files sit directly beside it as <atomic_id>.md. Report the task ID, actual changes, representative URIs, and unresolved decisions.

Boundaries

• Compile durable constraints only; do not promote preferences, facts, or one-task advice.
• Prefer faithful, non-empty applies_when conditions supported by the source. Empty applies_when means applicable in every situation except exception, not unknown.
• Request lifecycle changes only when the user explicitly authorizes them. Use ARCHIVE only when the user's instruction explicitly asks to delete, discard, or move a Rule to the recycle bin. Use PAUSE for pause, disable, deactivate, retire, stop-applying, or stop-using requests without deletion intent. Archived Rules are logically deleted: they are not compiler candidates and cannot be restored through Rule compilation.
• Use client connection configuration, not service-side model credentials. Do not switch instances or expose credentials to resolve a failed request.
• The API accepts at most 16 sources and 64000 instruction characters; source collection reads at most 128 files and 128000 characters. Split oversized material into self-contained policies with their conditions and exceptions rather than silently omitting content.
• Rule compilation requires readable text. Do not submit image, audio, or video sources.
• If a request fails or its status is unknown, check the task and saved files before retrying. Previously imported Resources are not rolled back when later Rule compilation fails.
• Do not treat an immediate empty search result as proof that writing failed; semantic indexing may still be pending.