roe-typescript 0.1.1 → 0.1.2

package/README.md

@@ -139,10 +139,252 @@ client.agents.jobs.downloadReference(jobId, resourceId)
 client.agents.jobs.deleteData(jobId)
 ```
 
+### Policies
+
+```typescript
+client.policies.list()                              // List policies
+client.policies.retrieve("policy-uuid")             // Get policy
+client.policies.create({ name, content, ... })      // Create policy
+client.policies.update("policy-uuid", { ... })      // Update policy
+client.policies.delete("policy-uuid")               // Delete policy
+```
+
+### Policy Versions
+
+```typescript
+client.policies.versions.list(policyId)
+client.policies.versions.retrieve(policyId, versionId)
+client.policies.versions.create({ policyId, content, ... })
+```
+
+## Rori Agents (Agentic Workflows)
+
+Rori agents are autonomous investigation agents that follow policies (SOPs), use tools, and produce structured verdicts. Unlike extraction engines which transform data, Rori agents reason over evidence, apply policy rules, and return dispositions. All Rori agents are policy-aware — you define the rules, they run the investigation.
+
+### Policies
+
+Policies define the rules, instructions, and disposition classifications that Rori agents follow. Creating a policy atomically creates the policy and its first version in one call:
+
+```typescript
+const policy = await client.policies.create({
+  name: "AML Investigation Policy",
+  content: {
+    guidelines: {
+      categories: [
+        {
+          title: "Structuring",
+          rules: [
+            {
+              title: "Cash structuring below reporting thresholds",
+              description: "Multiple deposits just under $10,000 within short timeframes",
+              flag: "RED_FLAG",
+            },
+          ],
+        },
+        {
+          title: "Layering",
+          rules: [
+            {
+              title: "Rapid movement between accounts",
+              description: "Funds transferred through multiple accounts to obscure origin",
+              flag: "RED_FLAG",
+              sub_rules: [
+                { title: "Cross-border wire transfers with no business purpose" },
+                { title: "Shell company intermediaries" },
+              ],
+            },
+          ],
+        },
+      ],
+    },
+    instructions: "Investigate the alert against each category. Use available data sources to gather evidence.",
+    dispositions: {
+      classifications: [
+        { name: "Suspicious", description: "Activity warrants SAR filing" },
+        { name: "Not Suspicious", description: "Activity has legitimate explanation" },
+        { name: "Needs Escalation", description: "Requires senior analyst review" },
+      ],
+    },
+    summary_template: {
+      template: "Investigation of {{subject}} found {{verdict}} based on {{findings_count}} findings.",
+    },
+  },
+});
+```
+
+Iterate on policies by creating new versions:
+
+```typescript
+// Create a new version (automatically becomes the current version)
+const newVersion = await client.policies.versions.create({
+  policyId: policy.id,
+  content: { /* Updated policy content */ },
+  versionName: "v2 - added layering rules",
+});
+
+// List all versions
+const versions = await client.policies.versions.list(policy.id);
+
+// Retrieve a specific version
+const version = await client.policies.versions.retrieve(policy.id, newVersion.id);
+
+// Update policy metadata
+await client.policies.update(policy.id, { name: "Updated Policy Name" });
+
+// List all policies
+const policies = await client.policies.list();
+
+// Delete a policy
+await client.policies.delete(policy.id);
+```
+
+### Policy Content Reference
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `guidelines` | object | Categories → Rules → Sub-rules hierarchy |
+| `guidelines.categories[].title` | string | Category name |
+| `guidelines.categories[].rules[].title` | string | Rule name |
+| `guidelines.categories[].rules[].description` | string | Rule details |
+| `guidelines.categories[].rules[].flag` | string | `"RED_FLAG"` or `"GREEN_FLAG"` |
+| `guidelines.categories[].rules[].sub_rules[].title` | string | Sub-rule name |
+| `instructions` | string | Free-text investigation instructions |
+| `dispositions.classifications[].name` | string | Outcome label (e.g., "Suspicious") |
+| `dispositions.classifications[].description` | string | When to apply this outcome |
+| `summary_template.template` | string | Handlebars template for report generation |
+| `optional.sar_narrative_template.template` | string | SAR narrative template (AML-specific) |
+
+### Product Compliance
+
+Analyze product listings against your compliance policy:
+
+```typescript
+const agent = await client.agents.create({
+  name: "Product Compliance",
+  engineClassId: "ProductPolicyEngine",
+  inputDefinitions: [
+    { key: "product_listings", data_type: "text/plain", description: "Product listing to analyze" },
+  ],
+  engineConfig: {
+    policy_version_id: policy.current_version_id!,
+    product_listings: "${product_listings}",
+  },
+});
+
+const outputs = await client.agents.runSync(agent.id, {
+  product_listings: "Nike Air Max 90, brand new, $45 — ships from Shenzhen",
+});
+```
+
+### AML Investigation
+
+Investigate anti-money laundering alerts:
+
+```typescript
+const agent = await client.agents.create({
+  name: "AML Investigation",
+  engineClassId: "AMLInvestigationEngine",
+  inputDefinitions: [
+    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
+  ],
+  engineConfig: {
+    policy_version_id: policy.current_version_id!,
+    alert_data: "${alert_data}",
+  },
+});
+
+const job = await client.agents.run({
+  agentId: agent.id,
+  inputs: { alert_data: "Customer John Doe, 5 cash deposits of $9,500 in 3 days" },
+});
+const result = await job.wait();
+```
+
+### Fraud Investigation
+
+Investigate fraud alerts and suspicious activity:
+
+```typescript
+const agent = await client.agents.create({
+  name: "Fraud Investigation",
+  engineClassId: "FraudInvestigationEngine",
+  inputDefinitions: [
+    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
+  ],
+  engineConfig: {
+    policy_version_id: policy.current_version_id!,
+    alert_data: "${alert_data}",
+  },
+});
+
+const job = await client.agents.run({
+  agentId: agent.id,
+  inputs: { alert_data: "Chargeback spike: 47 disputes in 24h from merchant ACME-1234" },
+});
+const result = await job.wait();
+```
+
+### Merchant Risk
+
+Analyze merchant risk profiles:
+
+```typescript
+const agent = await client.agents.create({
+  name: "Merchant Risk Analysis",
+  engineClassId: "MerchantRiskEngine",
+  inputDefinitions: [
+    { key: "merchant_context", data_type: "text/plain", description: "Merchant name and context" },
+  ],
+  engineConfig: {
+    policy_version_id: policy.current_version_id!,
+    merchant_context: "${merchant_context}",
+  },
+});
+
+const job = await client.agents.run({
+  agentId: agent.id,
+  inputs: { merchant_context: "ACME Corp - Online electronics retailer, MCC 5732" },
+});
+const result = await job.wait();
+```
+
+### Agent Configuration Options
+
+All Rori agents accept these options in `engineConfig`:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `policy_version_id` | string | — | Policy version UUID (required) |
+| `context_sources` | array | `[]` | External data sources (SQL connections, APIs) |
+| `enable_planning` | boolean | `true` | Enable autonomous tool-use planning |
+| `enable_memory` | boolean | `false` | Retain context across runs for the same entity |
+| `reasoning_effort` | string | `"medium"` | `"low"`, `"medium"`, or `"high"` |
+
+Example with advanced configuration:
+
+```typescript
+const agent = await client.agents.create({
+  name: "AML Investigation (Advanced)",
+  engineClassId: "AMLInvestigationEngine",
+  inputDefinitions: [
+    { key: "alert_data", data_type: "text/plain", description: "Alert data and context" },
+  ],
+  engineConfig: {
+    policy_version_id: policy.current_version_id!,
+    alert_data: "${alert_data}",
+    reasoning_effort: "high",
+    context_sources: [
+      { type: "sql", name: "Transactions DB", connection_id: "conn-uuid" },
+    ],
+  },
+});
+```
+
 ## Supported Models
 
 | Model | Value |
 |-------|-------|
+| GPT-5.4 | `gpt-5.4-2026-03-05` |
 | GPT-5.2 | `gpt-5.2-2025-12-11` |
 | GPT-5.1 | `gpt-5.1-2025-11-13` |
 | GPT-5 | `gpt-5-2025-08-07` |
@@ -152,24 +394,25 @@ client.agents.jobs.deleteData(jobId)
 | O3 Pro | `o3-pro-2025-06-10` |
 | O3 | `o3-2025-04-16` |
 | O4 Mini | `o4-mini-2025-04-16` |
-| GPT-4o | `gpt-4o-2024-11-20` |
-| Grok 4 | `grok-4-0709` |
-| Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` |
-| Claude Sonnet 4 | `claude-sonnet-4-20250514` |
-| Claude 3.7 Sonnet | `claude-3-7-sonnet-20250219` |
-| Claude Haiku 4.5 | `claude-haiku-4-5-20251001` |
-| Claude 3.5 Haiku | `claude-3-5-haiku-20241022` |
+| Claude Opus 4.6 | `claude-opus-4-6` |
+| Claude Sonnet 4.6 | `claude-sonnet-4-6` |
 | Claude Opus 4.5 | `claude-opus-4-5-20251101` |
+| Claude Sonnet 4.5 | `claude-sonnet-4-5-20250929` |
 | Claude Opus 4.1 | `claude-opus-4-1-20250805` |
 | Claude Opus 4 | `claude-opus-4-20250514` |
+| Claude Sonnet 4 | `claude-sonnet-4-20250514` |
+| Claude Haiku 4.5 | `claude-haiku-4-5-20251001` |
 | Gemini 3 Pro | `gemini-3-pro-preview` |
+| Gemini 3 Flash | `gemini-3-flash-preview` |
 | Gemini 2.5 Pro | `gemini-2.5-pro` |
 | Gemini 2.5 Flash | `gemini-2.5-flash` |
+| Grok 4 | `grok-4-0709` |
+| Grok 4.1 Fast Reasoning | `grok-4-1-fast-reasoning` |
 
 ## Engine Classes
 
 | Engine | ID |
-|--------|-----|
+|--------|----|
 | Multimodal Extraction | `MultimodalExtractionEngine` |
 | Document Insights | `PDFExtractionEngine` |
 | Document Segmentation | `PDFPageSelectionEngine` |
@@ -178,10 +421,12 @@ client.agents.jobs.deleteData(jobId)
 | Web Search | `URLFinderEngine` |
 | Perplexity Search | `PerplexitySearchEngine` |
 | Maps Search | `GoogleMapsEntityExtractionEngine` |
-| Merchant Risk | `MerchantRiskAnalysisEngine` |
-| Product Policy | `ProductPolicyEngine` |
 | LinkedIn Crawler | `LinkedInScraperEngine` |
 | Social Media | `SocialScraperEngine` |
+| Product Compliance | `ProductPolicyEngine` |
+| Merchant Risk | `MerchantRiskEngine` |
+| AML Investigation | `AMLInvestigationEngine` |
+| Fraud Investigation | `FraudInvestigationEngine` |
 
 ## Links
 

package/dist/api/policies.d.ts

@@ -0,0 +1,39 @@
+import { RoeConfig } from "../config.js";
+import { RoeHTTPClient } from "../utils/httpClient.js";
+import { PaginatedResponse } from "../models/responses.js";
+import { Policy, PolicyVersion } from "../models/policy.js";
+export declare class PolicyVersionsAPI {
+    private readonly policiesApi;
+    constructor(policiesApi: PoliciesAPI);
+    private get http();
+    list(policyId: string): Promise<PolicyVersion[]>;
+    retrieve(policyId: string, versionId: string): Promise<PolicyVersion>;
+    create(params: {
+        policyId: string;
+        content: Record<string, unknown>;
+        versionName?: string;
+        baseVersionId?: string;
+    }): Promise<PolicyVersion>;
+}
+export declare class PoliciesAPI {
+    readonly config: RoeConfig;
+    readonly httpClient: RoeHTTPClient;
+    readonly versions: PolicyVersionsAPI;
+    constructor(config: RoeConfig, httpClient: RoeHTTPClient);
+    list(params?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<PaginatedResponse<Policy>>;
+    retrieve(policyId: string): Promise<Policy>;
+    create(params: {
+        name: string;
+        content: Record<string, unknown>;
+        description?: string;
+        versionName?: string;
+    }): Promise<Policy>;
+    update(policyId: string, updates: {
+        name?: string;
+        description?: string;
+    }): Promise<Policy>;
+    delete(policyId: string): Promise<void>;
+}

package/dist/api/policies.js

@@ -0,0 +1,90 @@
+import { PaginationHelper } from "../utils/pagination.js";
+import { isUuidString } from "../utils/fileDetection.js";
+import { BadRequestError, RoeAPIException } from "../exceptions.js";
+/**
+ * Validates that a value is a valid UUID string.
+ * @throws BadRequestError if the value is not a valid UUID
+ */
+function validateUuid(value, fieldName) {
+    if (!isUuidString(value)) {
+        throw new BadRequestError(`Invalid ${fieldName}: "${value}" is not a valid UUID`, 400);
+    }
+}
+export class PolicyVersionsAPI {
+    constructor(policiesApi) {
+        this.policiesApi = policiesApi;
+    }
+    get http() {
+        return this.policiesApi.httpClient;
+    }
+    async list(policyId) {
+        validateUuid(policyId, "policyId");
+        const data = await this.http.get(`/v1/policies/${policyId}/versions/`);
+        if (Array.isArray(data))
+            return data;
+        return data.results ?? [];
+    }
+    async retrieve(policyId, versionId) {
+        validateUuid(policyId, "policyId");
+        validateUuid(versionId, "versionId");
+        return this.http.get(`/v1/policies/${policyId}/versions/${versionId}/`);
+    }
+    async create(params) {
+        validateUuid(params.policyId, "policyId");
+        if (params.baseVersionId !== undefined)
+            validateUuid(params.baseVersionId, "baseVersionId");
+        const payload = { content: params.content };
+        if (params.versionName !== undefined)
+            payload.version_name = params.versionName;
+        if (params.baseVersionId !== undefined)
+            payload.base_version_id = params.baseVersionId;
+        const data = await this.http.post({
+            url: `/v1/policies/${params.policyId}/versions/`,
+            json: payload,
+        });
+        if (!data.id) {
+            throw new RoeAPIException(`Unexpected response from server: ${JSON.stringify(data)}`);
+        }
+        // POST returns partial data; re-fetch to get the full version
+        return this.retrieve(params.policyId, data.id);
+    }
+}
+export class PoliciesAPI {
+    constructor(config, httpClient) {
+        this.config = config;
+        this.httpClient = httpClient;
+        this.versions = new PolicyVersionsAPI(this);
+    }
+    async list(params) {
+        const query = PaginationHelper.buildQueryParams(this.config.organizationId, params?.page, params?.pageSize);
+        return this.httpClient.get("/v1/policies/", query);
+    }
+    async retrieve(policyId) {
+        validateUuid(policyId, "policyId");
+        return this.httpClient.get(`/v1/policies/${policyId}/`);
+    }
+    async create(params) {
+        const payload = {
+            name: params.name,
+            content: params.content,
+            description: params.description ?? "",
+            organization_id: this.config.organizationId,
+        };
+        if (params.versionName !== undefined)
+            payload.version_name = params.versionName;
+        return this.httpClient.post({ url: "/v1/policies/", json: payload });
+    }
+    async update(policyId, updates) {
+        validateUuid(policyId, "policyId");
+        const payload = {};
+        if (updates.name !== undefined)
+            payload.name = updates.name;
+        if (updates.description !== undefined)
+            payload.description = updates.description;
+        return this.httpClient.put(`/v1/policies/${policyId}/`, payload);
+    }
+    async delete(policyId) {
+        validateUuid(policyId, "policyId");
+        await this.httpClient.delete(`/v1/policies/${policyId}/`);
+    }
+}

package/dist/client.d.ts

@@ -1,4 +1,5 @@
 import { AgentsAPI } from "./api/agents.js";
+import { PoliciesAPI } from "./api/policies.js";
 import { RoeAuth } from "./auth.js";
 import { RoeConfig, RoeConfigInput } from "./config.js";
 import { RoeHTTPClient } from "./utils/httpClient.js";
@@ -7,7 +8,9 @@ export declare class RoeClient {
     readonly auth: RoeAuth;
     readonly httpClient: RoeHTTPClient;
     private readonly _agents;
+    private readonly _policies;
     constructor(input?: RoeConfigInput);
     get agents(): AgentsAPI;
+    get policies(): PoliciesAPI;
     close(): void;
 }

package/dist/client.js

@@ -1,4 +1,5 @@
 import { AgentsAPI } from "./api/agents.js";
+import { PoliciesAPI } from "./api/policies.js";
 import { RoeAuth } from "./auth.js";
 import { RoeConfig } from "./config.js";
 import { RoeHTTPClient } from "./utils/httpClient.js";
@@ -8,10 +9,14 @@ export class RoeClient {
         this.auth = new RoeAuth(this.config);
         this.httpClient = new RoeHTTPClient(this.config, this.auth);
         this._agents = new AgentsAPI(this.config, this.httpClient);
+        this._policies = new PoliciesAPI(this.config, this.httpClient);
     }
     get agents() {
         return this._agents;
     }
+    get policies() {
+        return this._policies;
+    }
     close() {
         this.httpClient.close();
     }

package/dist/exceptions.js

@@ -43,6 +43,13 @@ export function extractErrorMessage(data, statusCode) {
     if (typeof data === "string") {
         return data;
     }
+    // DRF ValidationError returns a plain list like ["error message"]
+    if (Array.isArray(data)) {
+        if (data.length > 0) {
+            return data.map(String).join("; ");
+        }
+        return `HTTP ${statusCode} error`;
+    }
     if (typeof data === "object" && data !== null) {
         // Try common error message field names
         const obj = data;

package/dist/index.d.ts

@@ -4,7 +4,9 @@ export type { RoeConfigInput } from "./config.js";
 export { RoeAuth } from "./auth.js";
 export * from "./exceptions.js";
 export * from "./api/agents.js";
+export * from "./api/policies.js";
 export * from "./models/agent.js";
+export * from "./models/policy.js";
 export * from "./models/job.js";
 export * from "./models/responses.js";
 export * from "./models/file.js";

package/dist/index.js

@@ -3,7 +3,9 @@ export { RoeConfig } from "./config.js";
 export { RoeAuth } from "./auth.js";
 export * from "./exceptions.js";
 export * from "./api/agents.js";
+export * from "./api/policies.js";
 export * from "./models/agent.js";
+export * from "./models/policy.js";
 export * from "./models/job.js";
 export * from "./models/responses.js";
 export * from "./models/file.js";

package/dist/models/policy.d.ts

@@ -0,0 +1,19 @@
+export type Policy = {
+    id: string;
+    name: string;
+    description: string;
+    organization_id: string;
+    current_version_id: string | null;
+    created_at: string;
+    updated_at: string;
+};
+export type PolicyVersion = {
+    id: string;
+    version_name: string;
+    content: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+    policy: Policy | null;
+    created_by: Record<string, unknown> | null;
+    base_version_id: string | null;
+};

package/dist/models/policy.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "roe-typescript",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "TypeScript SDK for the Roe AI API (feature parity with roe-python).",
   "type": "module",
   "main": "dist/index.js",