aui-agent-builder 0.1.0

package/README.md

@@ -0,0 +1,311 @@
+# aui-agent-builder
+
+CLI tool for building and managing AUI conversational AI agents.
+
+## Overview
+
+`aui-agent-builder` provides a command-line interface to create, configure, validate, and deploy AUI agents. Agents are defined using `.aui.json` configuration files that specify parameters, entities, integrations, tools, and rules.
+
+## Installation
+
+```bash
+npm install -g aui-agent-builder
+```
+
+Or use directly with npx:
+
+```bash
+npx aui-agent-builder init my-agent
+```
+
+## Quick Start
+
+```bash
+# 1. Create a new agent project
+aui init my-agent
+cd my-agent
+
+# 2. Edit configuration files
+#    - agent.aui.json       → Agent identity and settings
+#    - parameters.aui.json  → Data parameters
+#    - entities.aui.json    → Parameter groups
+#    - integrations.aui.json → API connections
+#    - rules.aui.json       → Global rules
+#    - tools/*.aui.json     → Tool definitions
+
+# 3. Add integrations
+aui add-integration
+
+# 4. Add tools
+aui add-tool
+
+# 5. Add parameters
+aui add-param
+
+# 6. Validate your configuration
+aui validate
+
+# 7. Connect to AUI backend and push
+aui connect
+aui push
+```
+
+## Commands
+
+### `aui init [directory]`
+
+Initialize a new AUI agent project with clean template files.
+
+```bash
+aui init my-agent
+aui init my-agent --template banking
+aui init . --force  # Reinitialize in current directory
+```
+
+### `aui connect`
+
+Interactive setup to connect to the AUI backend. Validates API key, lets you select or create an agent, and downloads existing configuration.
+
+```bash
+aui connect
+aui connect --api-key <key> --org <id> --agent <code>
+```
+
+### `aui login`
+
+Configure API credentials (saved to `~/.aui/credentials.json`).
+
+```bash
+aui login
+aui login --api-key <key> --org <id> --profile production
+```
+
+### `aui validate [path]`
+
+Validate all `.aui.json` files in the project. Checks JSON syntax, schema compliance, and cross-file reference integrity.
+
+```bash
+aui validate
+aui validate ./path/to/agent --verbose
+```
+
+### `aui pull [agent-code]`
+
+Download agent configuration from the backend.
+
+```bash
+aui pull
+aui pull my-agent --force
+```
+
+### `aui push [agent-code]`
+
+Upload agent configuration to the backend. Validates before pushing.
+
+```bash
+aui push
+aui push my-agent --force --skip-validation
+```
+
+### `aui sync`
+
+Two-way sync with conflict resolution.
+
+```bash
+aui sync
+aui sync --dry-run  # Preview changes
+aui sync --force    # Force local → remote
+```
+
+### `aui add-integration`
+
+Add an integration (API, RAG, MCP) to the project interactively or from an OpenAPI spec.
+
+```bash
+aui add-integration
+aui add-integration --url https://api.example.com/openapi.json
+aui add-integration --file ./openapi.json
+```
+
+### `aui add-tool`
+
+Create a new tool definition interactively.
+
+```bash
+aui add-tool
+aui add-tool --code MY_CUSTOM_TOOL
+```
+
+### `aui add-param`
+
+Add a new parameter definition interactively.
+
+```bash
+aui add-param
+```
+
+## Project Structure
+
+```
+my-agent/
+├── agent.aui.json          # Agent metadata (code, version, objective, guardrails)
+├── parameters.aui.json     # Parameter definitions (data the agent works with)
+├── entities.aui.json       # Entity groups (related parameter collections)
+├── integrations.aui.json   # API integrations (endpoints, auth, request/response mapping)
+├── rules.aui.json          # Global constraint rules
+├── tools/                  # Tool definitions (one file per tool)
+│   ├── generative-ai.aui.json
+│   ├── transaction-search.aui.json
+│   └── create-dispute.aui.json
+├── .auirc                  # Project configuration
+└── .gitignore
+```
+
+## Configuration Files
+
+### agent.aui.json
+
+Defines the agent's identity:
+
+```json
+{
+  "agent": {
+    "code": "my-agent",
+    "version": "1.0.0",
+    "description": "Customer support agent",
+    "language": "en",
+    "objective": "Help users with account inquiries",
+    "guardrails": ["Be helpful and respectful"],
+    "tone_of_voice": "Professional and friendly"
+  }
+}
+```
+
+### parameters.aui.json
+
+Defines data parameters the agent works with:
+
+```json
+{
+  "parameters": [
+    {
+      "code": "transaction-id",
+      "description": "Unique transaction identifier",
+      "type": "string",
+      "usage": "all"
+    },
+    {
+      "code": "dispute-reason",
+      "description": "Reason for disputing a transaction",
+      "type": "string",
+      "usage": "input",
+      "values": ["not recognized", "unauthorized charge", "duplicate charge"]
+    }
+  ]
+}
+```
+
+### entities.aui.json
+
+Groups related parameters:
+
+```json
+{
+  "entities": [
+    {
+      "name": "Transactions",
+      "parameters": ["transaction-id", "transaction-amount", "transaction-status"]
+    }
+  ]
+}
+```
+
+### integrations.aui.json
+
+Defines API connections:
+
+```json
+{
+  "integrations": [
+    {
+      "type": "API",
+      "code": "transaction-search",
+      "settings": {
+        "endpoint": {
+          "url": "https://api.example.com/transactions",
+          "method": "GET",
+          "authentication": { "type": "API_KEY", "apiKey": "$API_KEY" }
+        },
+        "request_schema": [...],
+        "response_mapping": {...},
+        "test_curl": "curl ..."
+      }
+    }
+  ]
+}
+```
+
+### tools/*.aui.json
+
+Each tool defines a capability:
+
+```json
+{
+  "tool": {
+    "code": "TRANSACTION_SEARCH",
+    "objective": "When the user wants to look up transactions",
+    "status": true,
+    "main_tool": true,
+    "requires_confirmation": false,
+    "response_type": "text",
+    "config": {
+      "triggers": { "when": { "any": [] } },
+      "params": {
+        "required": ["user-id"],
+        "optional": ["card-number-suffix"]
+      }
+    },
+    "integrations": [{ "code": "transaction-search" }],
+    "rules": {
+      "pre": {},
+      "summary": {
+        "success": [{ "when": { "all": [] }, "then": { "action": "TEXT", "message": "..." } }]
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `AUI_API_KEY` | API key (highest priority) |
+| `AUI_API_URL` | Backend API URL |
+| `AUI_ORG_ID` | Organization ID |
+| `AUI_ACCOUNT_ID` | Account ID |
+| `AUI_NETWORK_ID` | Network ID |
+| `AUI_AGENT_CODE` | Agent code |
+
+### Configuration Priority
+
+1. Environment variables (highest)
+2. Project config (`.auirc`)
+3. User credentials (`~/.aui/credentials.json`)
+4. Defaults
+
+## Development
+
+```bash
+git clone <repo>
+cd aui-agent-builder
+npm install
+npm run build
+npm run dev -- init test-agent  # Run in development
+```
+
+## License
+
+MIT

package/bin/aui.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require('../dist/index.js');

package/dist/api-client/index.d.ts

@@ -0,0 +1,208 @@
+/**
+ * API Client for AUI Backend
+ *
+ * Handles all communication with the real AUI backend API.
+ *
+ * Base URL: https://api-staging.internal-aui.io/api/outer-bridge/
+ *
+ * Required headers on every request:
+ *   - auth-token: JWT from login
+ *   - account-id: Account identifier
+ *   - organization-id: Organization identifier
+ *   - x-aui-client: "AUI"
+ *   - x-aui-environment: "staging" | "production"
+ *   - x-aui-origin: "stores"
+ */
+import { AUIEnvironment } from '../config';
+export interface Account {
+    _id: string;
+    id: string;
+    name: string;
+    niceName: string;
+    status: 'ACTIVE' | 'INACTIVE';
+    organization: string;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface PaginatedResponse<T> {
+    docs: T[];
+    totalDocs: number;
+    limit: number;
+    totalPages: number;
+    page: number;
+    pagingCounter: number;
+    hasPrevPage: boolean;
+    hasNextPage: boolean;
+    prevPage: number | null;
+    nextPage: number | null;
+}
+export interface AccountsListResponse {
+    status: boolean;
+    data: PaginatedResponse<Account>;
+    message: string;
+    statusCode: number;
+}
+export interface Network {
+    _id: string;
+    id: string;
+    name: string;
+    niceName: string;
+    status: 'ACTIVE' | 'INACTIVE';
+    category?: {
+        _id: string;
+        name: string;
+    } | string;
+    account: string;
+    organization: string;
+    objective?: string;
+    createdBy: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface NetworksListResponse {
+    status: boolean;
+    data: Network[];
+    message: string;
+    statusCode: number;
+}
+export interface CreateNetworkResponse {
+    status: boolean;
+    data: Network;
+    message: string;
+    statusCode: number;
+}
+export interface AUIClientOptions {
+    /** API base URL (e.g. https://api-staging.internal-aui.io/api/outer-bridge) */
+    baseUrl: string;
+    /** JWT auth token from login */
+    authToken: string;
+    /** Account ID */
+    accountId?: string;
+    /** Organization ID */
+    organizationId?: string;
+    /** Environment */
+    environment?: AUIEnvironment;
+}
+export declare class AUIAPIError extends Error {
+    status: number;
+    statusText: string;
+    body?: unknown;
+    constructor(status: number, statusText: string, body?: unknown);
+}
+/**
+ * AUI Backend API Client
+ */
+export declare class AUIClient {
+    private baseUrl;
+    private authToken;
+    private accountId;
+    private organizationId;
+    private environment;
+    constructor(options: AUIClientOptions);
+    /**
+     * Update account/org IDs after initial connection
+     */
+    setScope(scope: {
+        accountId?: string;
+        organizationId?: string;
+    }): void;
+    /**
+     * Build request headers matching the real AUI API expectations
+     */
+    private getHeaders;
+    /**
+     * Make an HTTP request to the AUI backend
+     */
+    private request;
+    get<T>(endpoint: string): Promise<T>;
+    post<T>(endpoint: string, body?: unknown): Promise<T>;
+    put<T>(endpoint: string, body: unknown): Promise<T>;
+    patch<T>(endpoint: string, body: unknown): Promise<T>;
+    del<T>(endpoint: string): Promise<T>;
+    /** GET /network/v1/account - List accounts (projects) in the organization */
+    accounts: {
+        list: (page?: number, limit?: number) => Promise<AccountsListResponse>;
+    };
+    /**
+     * GET /network/v1/network - List agents in the organization/account
+     * POST /network/v1/network - Create a new agent
+     */
+    networks: {
+        /** List all agents (networks) for the current org + account */
+        list: () => Promise<NetworksListResponse>;
+        /** Create a new agent */
+        create: (data: {
+            name: string;
+            category: string;
+            objective?: string;
+        }) => Promise<CreateNetworkResponse>;
+        /** Get a single agent by ID */
+        get: (networkId: string) => Promise<{
+            status: boolean;
+            data: Network;
+        }>;
+    };
+    /** GET/POST /params */
+    params: {
+        list: () => Promise<unknown>;
+        create: (data: unknown) => Promise<unknown>;
+        update: (code: string, data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /tools */
+    tools: {
+        list: () => Promise<unknown>;
+        create: (data: unknown) => Promise<unknown>;
+        update: (code: string, data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /rules */
+    rules: {
+        list: () => Promise<unknown>;
+        update: (data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /general_settings */
+    generalSettings: {
+        get: () => Promise<unknown>;
+        update: (data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /entities */
+    entities: {
+        list: () => Promise<unknown>;
+        create: (data: unknown) => Promise<unknown>;
+        update: (code: string, data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /integrations */
+    integrations: {
+        list: () => Promise<unknown>;
+        create: (data: unknown) => Promise<unknown>;
+        update: (code: string, data: unknown) => Promise<unknown>;
+    };
+    /** GET/POST /files */
+    files: {
+        list: () => Promise<unknown>;
+        upload: (data: unknown) => Promise<unknown>;
+    };
+    /** GET /scrape */
+    scrape: {
+        get: (url: string) => Promise<unknown>;
+    };
+    /** GET /integration_mapping */
+    integrationMapping: {
+        get: (code: string) => Promise<unknown>;
+    };
+    conversations: {
+        newTask: (data: unknown) => Promise<unknown>;
+        newMessage: (data: {
+            task_id: string;
+            message: string;
+        }) => Promise<unknown>;
+        getInteraction: (id: string) => Promise<unknown>;
+        getTask: (id: string) => Promise<unknown>;
+    };
+    agents: {
+        list: () => Promise<unknown>;
+        create: (data: unknown) => Promise<unknown>;
+        get: (code: string) => Promise<unknown>;
+    };
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/api-client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/api-client/index.ts"],"names":[],"mappings":"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"}