@frontal-labs/ontology 0.0.1 → 1.0.1

package/README.md

@@ -1,32 +1,103 @@
 # @frontal-labs/ontology
 
-Ontology and model management APIs for schema, rules, and migrations.
+Client for the Frontal Ontology platform (`/v1/ontology/*`). The API is composed
+of independent subdomain services, each exposed as a namespace:
+`engine`, `objects`, `relationships`, `schemas`, `versions`, `validation`,
+`transformations`, `reasoning`, `rollouts`, `rollups`, `extract`, and `events`.
+(The `graph` subdomain is served by `@frontal-labs/graph`.)
 
 ## Installation
 
 ```bash
-bun add @frontal-labs/ontology @frontal-labs/core
+npm install @frontal-labs/ontology
 ```
 
+`@frontal-labs/core` is included automatically as a dependency.
+
+## Quick Start
+
+```ts
+import { ontology } from "@frontal-labs/ontology";
+
+// Generate an ontology with the engine, then browse object types.
+const proposal = await ontology.engine.generate({
+  description: "Model a billing dispute lifecycle with SLA states.",
+});
+const objectTypes = await ontology.objects.listObjectTypes({ limit: 10 });
+```
+
+The `ontology` singleton reads `FRONTAL_API_KEY` and
+`FRONTAL_ONTOLOGY_API_URL` from the environment.
+
 ## Usage
 
+### Explicit config
+
+```ts
+import { createOntologyClient } from "@frontal-labs/ontology";
+
+const ontology = createOntologyClient({
+  apiKey: process.env.FRONTAL_API_KEY!,
+  baseUrl: "https://api.frontal.dev/v1",
+});
+
+// Define/validate a schema via the schemas subdomain.
+await ontology.schemas.create({
+  name: "Invoice",
+  fields: [
+    { name: "amount", type: "number", required: true },
+    { name: "currency", type: "string", required: true },
+  ],
+});
+```
+
+### Shared client (multiple SDKs)
+
 ```ts
 import { FrontalClient } from "@frontal-labs/core";
 import { createOntologyClient } from "@frontal-labs/ontology";
 
 const client = new FrontalClient({
   apiKey: process.env.FRONTAL_API_KEY!,
-  baseUrl: process.env.FRONTAL_API_URL ?? "https://api.frontal.dev/v1",
+  baseUrl: "https://api.frontal.dev/v1",
 });
 
 const ontology = createOntologyClient(client);
+```
+
+### Validate a payload
+
+```ts
+await ontology.validation.validatePayload({
+  objectType: "Incident",
+  payload: { severity: "high" },
+});
+```
+
+### AI-powered generation & inference
+
+```ts
+const proposal = await ontology.engine.generate({
+  description: "Model a billing dispute lifecycle with ownership and SLA states.",
+  substrates: ["billing", "support"],
+});
+const inferred = await ontology.engine.inferClasses({ samples: [] });
+```
 
-const models = await ontology.list({ limit: 10 });
-await ontology.create({ name: "invoice", fields: [{ name: "amount", type: "number", required: true }] });
+### Versions & rollouts
+
+```ts
+const bundle = await ontology.versions.createReleaseBundle({ version: "2.0.0" });
+const rollout = await ontology.rollouts.create({ bundleId: bundle.id });
+await ontology.rollouts.start(rollout.id);
+const status = await ontology.rollouts.status(rollout.id);
 ```
 
-## Configuration
+## Environment Variables
 
-- `FRONTAL_API_KEY`
-- `FRONTAL_ONTOLOGY_API_URL` (optional)
-- `FRONTAL_API_URL` (fallback)
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FRONTAL_API_KEY` | Yes | — | Frontal API authentication key |
+| `FRONTAL_API_URL` | No | `https://api.frontal.dev/v1` | Base URL for the Frontal API |
+| `FRONTAL_ENV` | No | `development` | Runtime environment (`development`, `test`, `production`) |
+| `FRONTAL_DEBUG` | No | `false` | Enable debug logging |

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import { FrontalClient } from "@frontal-labs/core";
+import { OntologySdk } from "./sdk";
+/**
+ * Configuration for creating an {@link OntologySdk} client standalone.
+ *
+ * @property apiKey - Frontal API key.
+ * @property baseUrl - Override the default ontology API base URL.
+ * @property timeout - Request timeout in milliseconds (default 30_000).
+ * @property maxRetries - Maximum number of retry attempts (default 3).
+ */
+export interface OntologyClientConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    maxRetries?: number;
+}
+/**
+ * Creates an {@link OntologySdk} from either an existing {@link FrontalClient}
+ * or a plain configuration object.
+ *
+ * @param config - A pre-configured FrontalClient or config options.
+ * @returns A fully-initialized OntologySdk.
+ */
+export declare function createOntologyClient(config: OntologyClientConfig | FrontalClient): OntologySdk;
+/**
+ * Convenience singleton that lazily creates an {@link OntologySdk} using the
+ * default environment configuration.
+ *
+ * @example
+ * ```ts
+ * import { ontology } from "@frontal-labs/ontology";
+ * const models = await ontology.schemas.list();
+ * ```
+ */
+export declare const ontology: OntologySdk;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAGd,MAAM,oBAAoB,CAAC;AAO5B,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC;AAGpC;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAAG,aAAa,GAC3C,WAAW,CAAC;AA0Bf;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,aAWnB,CAAC"}

package/dist/constants.d.ts

@@ -6,4 +6,16 @@ export declare const DEFAULT_ONTOLOGY_BASE_URL = "https://api.frontal.dev/v1";
  * Package version.
  */
 export declare const VERSION = "0.0.1";
+/**
+ * Default timeout.
+ */
+export declare const DEFAULT_TIMEOUT = 30000;
+/**
+ * Default max retry number.
+ */
+export declare const DEFAULT_MAX_RETRIES = 3;
+/**
+ * Default retry delay.
+ */
+export declare const DEFAULT_RETRY_DELAY = 1000;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,yBAAyB,+BAA+B,CAAC;AAEtE;;GAEG;AACH,eAAO,MAAM,OAAO,UAAU,CAAC;AAE/B;;GAEG;AACH,eAAO,MAAM,eAAe,QAAS,CAAC;AAEtC;;GAEG;AACH,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAErC;;GAEG;AACH,eAAO,MAAM,mBAAmB,OAAO,CAAC"}

package/dist/index.d.ts

@@ -1,17 +1,10 @@
-import { FrontalClient } from "@frontal-labs/core";
-import { OntologyService } from "./service";
-/** Config for standalone usage without @frontal-labs/core */
-export interface OntologyClientConfig {
-    apiKey: string;
-    baseUrl?: string;
-    timeout?: number;
-    maxRetries?: number;
-}
-/** Create from a FrontalClient instance */
-export declare function createOntologyClient(client: FrontalClient): OntologyService;
-/** Create standalone with just config */
-export declare function createOntologyClient(config: OntologyClientConfig): OntologyService;
-export declare const ontology: OntologyService;
+/**
+ * @frontal-labs/ontology
+ *
+ * Define and manage Frontal ontology schemas and objects.
+ */
+export { createOntologyClient, ontology, type OntologyClientConfig, } from "./client";
+export { DEFAULT_ONTOLOGY_BASE_URL, VERSION } from "./constants";
 export * from "./schemas";
-export { OntologyService } from "./service";
+export { OntologySdk } from "./sdk";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAgC,MAAM,oBAAoB,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAE5C,6DAA6D;AAC7D,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,2CAA2C;AAC3C,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,aAAa,GAAG,eAAe,CAAC;AAC7E,yCAAyC;AACzC,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,oBAAoB,GAC3B,eAAe,CAAC;AAyBnB,eAAO,MAAM,QAAQ,iBAAgD,CAAC;AAEtE,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,oBAAoB,EACpB,QAAQ,EACR,KAAK,oBAAoB,GAC1B,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,yBAAyB,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AACjE,cAAc,WAAW,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,MAAM,OAAO,CAAC"}