faces-cli 1.0.0 → 1.2.0

package/dist/commands/face/create.d.ts

@@ -4,6 +4,7 @@ export default class FaceCreate extends BaseCommand {
     static flags: {
         name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         username: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         attr: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tool: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/face/create.js

@@ -7,6 +7,7 @@ export default class FaceCreate extends BaseCommand {
         ...BaseCommand.baseFlags,
         name: Flags.string({ description: 'Display name', required: true }),
         username: Flags.string({ description: 'Unique username slug', required: true }),
+        formula: Flags.string({ description: 'Boolean formula over owned concrete face usernames (e.g. "a | b", "(a | b) - c"). Creates a synthetic face.' }),
         attr: Flags.string({ description: 'Attribute KEY=VALUE (repeatable)', multiple: true }),
         tool: Flags.string({ description: 'Tool name to enable (repeatable)', multiple: true }),
     };
@@ -14,18 +15,26 @@ export default class FaceCreate extends BaseCommand {
     async run() {
         const { flags } = await this.parse(FaceCreate);
         const client = this.makeClient(flags);
-        const parsedAttrs = {};
-        for (const a of flags.attr ?? []) {
-            if (!a.includes('='))
-                this.error(`Attributes must be KEY=VALUE, got: ${a}`);
-            const idx = a.indexOf('=');
-            parsedAttrs[a.slice(0, idx).trim()] = a.slice(idx + 1).trim();
+        if (flags.formula && (flags.attr?.length || flags.tool?.length)) {
+            this.error('--formula cannot be combined with --attr or --tool. Synthetic faces do not have compiled knowledge.');
         }
         const payload = { name: flags.name, username: flags.username };
-        if (Object.keys(parsedAttrs).length > 0)
-            payload.facts = parsedAttrs;
-        if (flags.tool && flags.tool.length > 0)
-            payload.tools = flags.tool;
+        if (flags.formula) {
+            payload.formula = flags.formula;
+        }
+        else {
+            const parsedAttrs = {};
+            for (const a of flags.attr ?? []) {
+                if (!a.includes('='))
+                    this.error(`Attributes must be KEY=VALUE, got: ${a}`);
+                const idx = a.indexOf('=');
+                parsedAttrs[a.slice(0, idx).trim()] = a.slice(idx + 1).trim();
+            }
+            if (Object.keys(parsedAttrs).length > 0)
+                payload.facts = parsedAttrs;
+            if (flags.tool && flags.tool.length > 0)
+                payload.tools = flags.tool;
+        }
         let data;
         try {
             data = await client.post('/v1/faces', { body: payload });

package/dist/commands/face/diff.d.ts

@@ -0,0 +1,11 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceDiff extends BaseCommand {
+    static description: string;
+    static flags: {
+        face: import("@oclif/core/interfaces").OptionFlag<string[], import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/diff.js

@@ -0,0 +1,54 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceDiff extends BaseCommand {
+    static description = 'Compare owned faces pairwise across all centroid components';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        face: Flags.string({
+            description: 'Face username to include (repeatable, min 2)',
+            multiple: true,
+            required: true,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(FaceDiff);
+        const client = this.makeClient(flags);
+        if (flags.face.length < 2) {
+            this.error('At least 2 --face values are required');
+        }
+        const params = { faces: flags.face.join(',') };
+        let data;
+        try {
+            data = await client.get('/v1/faces/diff', { params });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!this.jsonEnabled()) {
+            const res = data;
+            const faces = res.faces;
+            const components = ['face', 'beta', 'delta', 'epsilon'];
+            for (let i = 0; i < faces.length; i++) {
+                for (let j = i + 1; j < faces.length; j++) {
+                    const a = faces[i];
+                    const b = faces[j];
+                    const scores = res.similarity[a][b];
+                    const parts = components.map(c => {
+                        const v = scores[c];
+                        return `${c}: ${v === null ? '—' : v.toFixed(2)}`;
+                    });
+                    this.log(`${a}  ↔  ${b}   ${parts.join('   ')}`);
+                }
+            }
+            this.log('');
+            const updated = Object.entries(res.centroids_updated_at)
+                .map(([face, ts]) => `${face} ${new Date(ts * 1000).toISOString().slice(0, 10)}`)
+                .join(', ');
+            this.log(`Centroids updated: ${updated}`);
+        }
+        return data;
+    }
+}

package/dist/commands/face/get.js

@@ -21,8 +21,32 @@ export default class FaceGet extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled())
-            this.printHuman(data);
+        if (!this.jsonEnabled()) {
+            const f = data;
+            this.log(`id:        ${f.id}`);
+            this.log(`uid:       ${f.uid}`);
+            this.log(`name:      ${f.name}`);
+            this.log(`owned_by:  ${f.owned_by}`);
+            this.log(`created:   ${new Date(f.created * 1000).toISOString().slice(0, 10)}`);
+            if (f.formula) {
+                this.log(`formula:   ${f.formula}`);
+                this.log(`type:      synthetic`);
+            }
+            else {
+                this.log(`type:      concrete`);
+                if (f.basic_facts && Object.keys(f.basic_facts).length > 0) {
+                    this.log('basic_facts:');
+                    for (const [k, v] of Object.entries(f.basic_facts)) {
+                        const display = typeof v === 'object' ? JSON.stringify(v) : v;
+                        this.log(`  ${k}: ${display}`);
+                    }
+                }
+                if (f.default_tools && f.default_tools.length > 0)
+                    this.log(`default_tools: ${f.default_tools.join(', ')}`);
+                if (f.default_model)
+                    this.log(`default_model: ${f.default_model}`);
+            }
+        }
         return data;
     }
 }

package/dist/commands/face/list.js

@@ -17,8 +17,20 @@ export default class FaceList extends BaseCommand {
                 this.error(`Error (${err.statusCode}): ${err.message}`);
             throw err;
         }
-        if (!this.jsonEnabled())
-            this.printHuman(data);
+        if (!this.jsonEnabled()) {
+            const faces = (data.data) ?? data;
+            if (faces.length === 0) {
+                this.log('(no faces)');
+            }
+            else {
+                const idWidth = Math.max(...faces.map(f => f.id.length));
+                const nameWidth = Math.max(...faces.map(f => f.name.length));
+                for (const f of faces) {
+                    const synthetic = f.formula ? `  [synthetic: ${f.formula}]` : '';
+                    this.log(`${f.id.padEnd(idWidth)}  ${f.name.padEnd(nameWidth)}${synthetic}`);
+                }
+            }
+        }
         return data;
     }
 }

package/dist/commands/face/neighbors.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../base.js';
+export default class FaceNeighbors extends BaseCommand {
+    static description: string;
+    static flags: {
+        k: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+        component: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        direction: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'api-key': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    };
+    static args: {
+        face_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+    };
+    run(): Promise<unknown>;
+}

package/dist/commands/face/neighbors.js

@@ -0,0 +1,62 @@
+import { Args, Flags } from '@oclif/core';
+import { BaseCommand } from '../../base.js';
+import { FacesAPIError } from '../../client.js';
+export default class FaceNeighbors extends BaseCommand {
+    static description = 'Find the most similar or dissimilar owned faces to a given face';
+    static flags = {
+        ...BaseCommand.baseFlags,
+        k: Flags.integer({
+            description: 'Number of results (1–20)',
+            default: 5,
+            min: 1,
+            max: 20,
+        }),
+        component: Flags.string({
+            description: 'Centroid component to rank on (beta, delta, epsilon are the principal components of a face; face is their composite)',
+            options: ['face', 'beta', 'delta', 'epsilon'],
+            default: 'face',
+        }),
+        direction: Flags.string({
+            description: 'nearest (most similar) or furthest (most dissimilar)',
+            options: ['nearest', 'furthest'],
+            default: 'nearest',
+        }),
+    };
+    static args = {
+        face_id: Args.string({ description: 'Face username', required: true }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FaceNeighbors);
+        const client = this.makeClient(flags);
+        const params = {
+            k: String(flags.k),
+            component: flags.component,
+            direction: flags.direction,
+        };
+        let data;
+        try {
+            data = await client.get(`/v1/faces/${args.face_id}/neighbors`, { params });
+        }
+        catch (err) {
+            if (err instanceof FacesAPIError)
+                this.error(`Error (${err.statusCode}): ${err.message}`);
+            throw err;
+        }
+        if (!this.jsonEnabled()) {
+            const res = data;
+            const label = res.direction === 'nearest' ? 'Nearest' : 'Most dissimilar';
+            this.log(`${label} neighbors to ${res.face} (by ${res.component}):`);
+            this.log('');
+            if (res.neighbors.length === 0) {
+                this.log('  (none)');
+            }
+            else {
+                for (const [i, n] of res.neighbors.entries()) {
+                    const updated = new Date(n.centroid_updated_at * 1000).toISOString().slice(0, 10);
+                    this.log(`  ${i + 1}. ${n.face.padEnd(20)} ${n.similarity.toFixed(2)}   (centroid updated ${updated})`);
+                }
+            }
+        }
+        return data;
+    }
+}

package/dist/commands/face/update.d.ts

@@ -3,6 +3,7 @@ export default class FaceUpdate extends BaseCommand {
     static description: string;
     static flags: {
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        formula: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         attr: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         tool: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
         'base-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/face/update.js

@@ -6,6 +6,7 @@ export default class FaceUpdate extends BaseCommand {
     static flags = {
         ...BaseCommand.baseFlags,
         name: Flags.string({ description: 'New display name' }),
+        formula: Flags.string({ description: 'New boolean formula (synthetic faces only)' }),
         attr: Flags.string({ description: 'Update attribute KEY=VALUE (repeatable)', multiple: true }),
         tool: Flags.string({ description: 'Tool names to set (replaces list, repeatable)', multiple: true }),
     };
@@ -18,6 +19,8 @@ export default class FaceUpdate extends BaseCommand {
         const payload = {};
         if (flags.name)
             payload.name = flags.name;
+        if (flags.formula)
+            payload.formula = flags.formula;
         if (flags.attr && flags.attr.length > 0) {
             const parsed = {};
             for (const a of flags.attr) {

package/oclif.manifest.json

@@ -1365,6 +1365,13 @@
           "multiple": false,
           "type": "option"
         },
+        "formula": {
+          "description": "Boolean formula over owned concrete face usernames (e.g. \"a | b\", \"(a | b) - c\"). Creates a synthetic face.",
+          "name": "formula",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "attr": {
           "description": "Attribute KEY=VALUE (repeatable)",
           "name": "attr",
@@ -1461,6 +1468,67 @@
         "delete.js"
       ]
     },
+    "face:diff": {
+      "aliases": [],
+      "args": {},
+      "description": "Compare owned faces pairwise across all centroid components",
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "base-url": {
+          "description": "API base URL",
+          "env": "FACES_BASE_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "token": {
+          "description": "JWT bearer token",
+          "env": "FACES_TOKEN",
+          "name": "token",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-key": {
+          "description": "API key",
+          "env": "FACES_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "face": {
+          "description": "Face username to include (repeatable, min 2)",
+          "name": "face",
+          "required": true,
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "face:diff",
+      "pluginAlias": "faces-cli",
+      "pluginName": "faces-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "face",
+        "diff.js"
+      ]
+    },
     "face:get": {
       "aliases": [],
       "args": {
@@ -1573,6 +1641,99 @@
         "list.js"
       ]
     },
+    "face:neighbors": {
+      "aliases": [],
+      "args": {
+        "face_id": {
+          "description": "Face username",
+          "name": "face_id",
+          "required": true
+        }
+      },
+      "description": "Find the most similar or dissimilar owned faces to a given face",
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "base-url": {
+          "description": "API base URL",
+          "env": "FACES_BASE_URL",
+          "name": "base-url",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "token": {
+          "description": "JWT bearer token",
+          "env": "FACES_TOKEN",
+          "name": "token",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "api-key": {
+          "description": "API key",
+          "env": "FACES_API_KEY",
+          "name": "api-key",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "k": {
+          "description": "Number of results (1–20)",
+          "name": "k",
+          "default": 5,
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "component": {
+          "description": "Centroid component to rank on (beta, delta, epsilon are the principal components of a face; face is their composite)",
+          "name": "component",
+          "default": "face",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "face",
+            "beta",
+            "delta",
+            "epsilon"
+          ],
+          "type": "option"
+        },
+        "direction": {
+          "description": "nearest (most similar) or furthest (most dissimilar)",
+          "name": "direction",
+          "default": "nearest",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "nearest",
+            "furthest"
+          ],
+          "type": "option"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "face:neighbors",
+      "pluginAlias": "faces-cli",
+      "pluginName": "faces-cli",
+      "pluginType": "core",
+      "strict": true,
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "dist",
+        "commands",
+        "face",
+        "neighbors.js"
+      ]
+    },
     "face:stats": {
       "aliases": [],
       "args": {},
@@ -1675,6 +1836,13 @@
           "multiple": false,
           "type": "option"
         },
+        "formula": {
+          "description": "New boolean formula (synthetic faces only)",
+          "name": "formula",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
         "attr": {
           "description": "Update attribute KEY=VALUE (repeatable)",
           "name": "attr",
@@ -2715,5 +2883,5 @@
       ]
     }
   },
-  "version": "1.0.0"
+  "version": "1.2.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "faces-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "CLI for the Faces AI platform",
   "type": "module",
   "author": "sybileak <sybileak@proton.me>",
@@ -31,18 +31,40 @@
     "bin": "faces",
     "dirname": "faces",
     "commands": "./dist/commands",
-    "plugins": ["@oclif/plugin-help"],
+    "plugins": [
+      "@oclif/plugin-help"
+    ],
     "topics": {
-      "auth": { "description": "Login, logout, register, and identity" },
-      "face": { "description": "Create and manage face personas" },
-      "chat": { "description": "Run inference via a face" },
-      "compile": { "description": "Compile source texts into a face" },
-      "compile doc": { "description": "Document operations" },
-      "compile thread": { "description": "Thread operations" },
-      "keys": { "description": "Manage API keys (JWT required)" },
-      "billing": { "description": "Credits, subscription, and usage" },
-      "account": { "description": "Account-level operations" },
-      "config": { "description": "Local CLI configuration" }
+      "auth": {
+        "description": "Login, logout, register, and identity"
+      },
+      "face": {
+        "description": "Create and manage face personas"
+      },
+      "chat": {
+        "description": "Run inference via a face"
+      },
+      "compile": {
+        "description": "Compile source texts into a face"
+      },
+      "compile doc": {
+        "description": "Document operations"
+      },
+      "compile thread": {
+        "description": "Thread operations"
+      },
+      "keys": {
+        "description": "Manage API keys (JWT required)"
+      },
+      "billing": {
+        "description": "Credits, subscription, and usage"
+      },
+      "account": {
+        "description": "Account-level operations"
+      },
+      "config": {
+        "description": "Local CLI configuration"
+      }
     }
   },
   "files": [