@frontal-labs/ontology 0.0.1

package/src/index.ts

@@ -0,0 +1,45 @@
+import { FrontalClient, getDefaultClient, HttpClient } 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 function createOntologyClient(client: FrontalClient): OntologyService;
+/** Create standalone with just config */
+export function createOntologyClient(
+  config: OntologyClientConfig
+): OntologyService;
+export function createOntologyClient(
+  clientOrConfig: FrontalClient | OntologyClientConfig
+): OntologyService {
+  if (clientOrConfig instanceof FrontalClient) {
+    return new OntologyService(clientOrConfig._http);
+  }
+  const http = new HttpClient({
+    apiKey: clientOrConfig.apiKey,
+    baseUrl:
+      clientOrConfig.baseUrl ??
+      process.env.FRONTAL_ONTOLOGY_API_URL ??
+      process.env.FRONTAL_API_URL ??
+      "https://api.frontal.dev/v1",
+    timeout: clientOrConfig.timeout ?? 30000,
+    maxRetries: clientOrConfig.maxRetries ?? 3,
+    retryDelay: 1000,
+    headers: {},
+    environment: "production",
+    debug: false,
+  });
+  return new OntologyService(http);
+}
+
+// Default instance that works automatically with environment variables
+export const ontology = new OntologyService(getDefaultClient()._http);
+
+export * from "./schemas";
+export { OntologyService } from "./service";

package/src/keys.ts

@@ -0,0 +1,29 @@
+import { createEnv } from "@t3-oss/env-core";
+import { z } from "zod";
+
+export const env = createEnv({
+  server: {
+    NODE_ENV: z
+      .enum(["development", "test", "production"])
+      .default("development"),
+    FRONTAL_API_URL: z
+      .url()
+      .optional()
+      .refine((val) => !(process.env.NODE_ENV === "production") || !!val, {
+        message: "FRONTAL_API_URL is required in production",
+      }),
+    FRONTAL_API_KEY: z
+      .string()
+      .min(1)
+      .optional()
+      .refine((val) => !(process.env.NODE_ENV === "production") || !!val, {
+        message: "FRONTAL_API_KEY is required in production",
+      }),
+  },
+  runtimeEnv: {
+    NODE_ENV: process.env.NODE_ENV,
+    FRONTAL_API_URL: process.env.FRONTAL_API_URL,
+    FRONTAL_API_KEY: process.env.FRONTAL_API_KEY,
+  },
+  emptyStringAsUndefined: true,
+});

package/src/schemas.ts

@@ -0,0 +1,191 @@
+import { timestampSchema } from "@frontal-labs/core";
+import { z } from "zod";
+
+export const FieldTypeSchema = z.enum([
+  "string",
+  "integer",
+  "float",
+  "boolean",
+  "uuid",
+  "timestamp",
+  "currency",
+  "json",
+  "array",
+  "enum",
+  "vector",
+  "text",
+]);
+
+export const RelationshipTypeSchema = z.enum([
+  "hasOne",
+  "hasMany",
+  "belongsTo",
+  "manyToMany",
+]);
+
+export const FieldDefinitionSchema = z
+  .object({
+    type: FieldTypeSchema,
+    required: z.boolean().default(false),
+    primary: z.boolean().default(false),
+    unique: z.boolean().default(false),
+    default: z.unknown().optional(),
+    substrate: z.string().optional(),
+    computed: z.boolean().optional(),
+    derivedBy: z.string().optional(),
+    cache: z
+      .object({
+        ttl: z.string(),
+      })
+      .optional(),
+    auto: z.boolean().optional(),
+    enum: z.array(z.string()).optional(),
+    dimensions: z.number().int().optional(),
+    items: z.string().optional(),
+    description: z.string().optional(),
+  })
+  .passthrough();
+
+export const RelationshipDefinitionSchema = z
+  .object({
+    name: z.string().optional(),
+    type: RelationshipTypeSchema,
+    targetEntity: z.string(),
+    foreignKey: z.string().optional(),
+    substrate: z.string().optional(),
+    cascade: z
+      .object({
+        delete: z.enum(["hard", "soft", "restrict", "nullify"]),
+        update: z.enum(["cascade", "restrict"]),
+      })
+      .optional(),
+    computed: z.record(z.string(), z.unknown()).optional(),
+    description: z.string().optional(),
+  })
+  .passthrough();
+
+export const SubstrateRoutingSchema = z
+  .object({
+    operational: z.string().optional(),
+    analytical: z.string().optional(),
+    semantic: z.string().optional(),
+    cache: z.string().optional(),
+  })
+  .passthrough();
+
+export const SemanticMetadataSchema = z
+  .object({
+    description: z.string().optional(),
+    lifecycle: z.array(z.string()).optional(),
+    criticalFields: z.array(z.string()).optional(),
+    significantEvents: z.array(z.string()).optional(),
+    tags: z.array(z.string()).optional(),
+  })
+  .passthrough();
+
+export const IndexDefinitionSchema = z
+  .object({
+    name: z.string().optional(),
+    fields: z.array(z.string()).min(1),
+    substrate: z.string().optional(),
+    unique: z.boolean().default(false),
+    type: z.enum(["btree", "hash", "gin", "gist", "brin"]).default("btree"),
+  })
+  .passthrough();
+
+export const ModelDefinitionSchema = z
+  .object({
+    name: z.string(),
+    displayName: z.string().optional(),
+    description: z.string().optional(),
+    extends: z.string().optional(),
+    mixins: z.array(z.string()).optional(),
+    fields: z.record(z.string(), FieldDefinitionSchema),
+    relationships: z
+      .record(z.string(), RelationshipDefinitionSchema)
+      .optional(),
+    substrates: SubstrateRoutingSchema.optional(),
+    semantics: SemanticMetadataSchema.optional(),
+    indexes: z.array(IndexDefinitionSchema).optional(),
+    status: z.enum(["draft", "active", "deprecated"]).default("draft"),
+  })
+  .strict();
+
+export const ModelSchema = ModelDefinitionSchema.extend({
+  id: z.string(),
+  version: z.number().int(),
+  createdAt: timestampSchema,
+  updatedAt: timestampSchema,
+  entityCount: z.number().int().optional(),
+}).passthrough();
+
+export const MigrationPlanSchema = z
+  .object({
+    id: z.string(),
+    modelId: z.string(),
+    fromVersion: z.number().int(),
+    toVersion: z.number().int(),
+    changes: z.array(
+      z.object({
+        type: z.enum([
+          "add-field",
+          "remove-field",
+          "modify-field",
+          "add-relationship",
+          "remove-relationship",
+        ]),
+        description: z.string(),
+        impact: z.enum(["breaking", "non-breaking", "data-loss"]),
+        sql: z.string().optional(),
+      })
+    ),
+    riskLevel: z.enum(["low", "medium", "high", "critical"]),
+    estimatedDowntime: z.string().optional(),
+    rolloutStrategy: z.enum([
+      "zero-downtime",
+      "maintenance-window",
+      "immediate",
+    ]),
+    createdAt: timestampSchema,
+  })
+  .passthrough();
+
+export const RuleDefinitionSchema = z
+  .object({
+    name: z.string(),
+    description: z.string().optional(),
+    entityTypes: z.array(z.string()).min(1),
+    condition: z.string(),
+    action: z.enum(["validate", "transform", "notify"]),
+    severity: z.enum(["error", "warning", "info"]),
+    enabled: z.boolean().default(true),
+  })
+  .strict();
+
+export const MixinDefinitionSchema = z
+  .object({
+    name: z.string(),
+    description: z.string().optional(),
+    fields: z.record(z.string(), FieldDefinitionSchema),
+    relationships: z
+      .record(z.string(), RelationshipDefinitionSchema)
+      .optional(),
+    appliesTo: z.array(z.string()).optional(),
+  })
+  .strict();
+
+// Inferred types
+export type FieldType = z.infer<typeof FieldTypeSchema>;
+export type RelationshipType = z.infer<typeof RelationshipTypeSchema>;
+export type FieldDefinition = z.infer<typeof FieldDefinitionSchema>;
+export type RelationshipDefinition = z.infer<
+  typeof RelationshipDefinitionSchema
+>;
+export type SubstrateRouting = z.infer<typeof SubstrateRoutingSchema>;
+export type SemanticMetadata = z.infer<typeof SemanticMetadataSchema>;
+export type IndexDefinition = z.infer<typeof IndexDefinitionSchema>;
+export type ModelDefinition = z.infer<typeof ModelDefinitionSchema>;
+export type Model = z.infer<typeof ModelSchema>;
+export type MigrationPlan = z.infer<typeof MigrationPlanSchema>;
+export type RuleDefinition = z.infer<typeof RuleDefinitionSchema>;
+export type MixinDefinition = z.infer<typeof MixinDefinitionSchema>;

package/src/service.ts

@@ -0,0 +1,269 @@
+import {
+  createPageResult,
+  type HttpClient,
+  type PageResult,
+  type PaginationMeta,
+} from "@frontal-labs/core";
+import type { z } from "zod";
+import * as S from "./schemas";
+
+const asPagePayload = <T>(
+  raw: unknown
+): {
+  data: T[];
+  pagination: PaginationMeta;
+  meta?: unknown;
+} =>
+  raw as {
+    data: T[];
+    pagination: PaginationMeta;
+    meta?: unknown;
+  };
+
+export class OntologyService {
+  constructor(private readonly http: HttpClient) {}
+
+  use(name: string): ModelAccessor {
+    return new ModelAccessor(name, this.http);
+  }
+
+  async list(
+    opts: {
+      status?: z.infer<typeof S.ModelSchema>["status"];
+      substrate?: string;
+      limit?: number;
+      cursor?: string;
+    } = {}
+  ): Promise<PageResult<S.Model>> {
+    const raw = await this.http.get("/ontology/engine/runs", opts);
+    return createPageResult(asPagePayload<S.Model>(raw), (cursor) =>
+      this.list({ ...opts, cursor })
+    );
+  }
+
+  async create(definition: S.ModelDefinition): Promise<S.Model> {
+    const body = S.ModelDefinitionSchema.parse(definition);
+    return this.http.post("/ontology/engine/runs", body);
+  }
+
+  async validate(
+    definition: S.ModelDefinition
+  ): Promise<{ valid: boolean; errors?: unknown[]; warnings?: unknown[] }> {
+    const body = S.ModelDefinitionSchema.parse(definition);
+    return this.http.post("/ontology/engine/ontologies/validate", body);
+  }
+
+  async checkIntegrity(): Promise<{ valid: boolean; violations?: unknown[] }> {
+    return this.http.get("/ontology/engine/health");
+  }
+
+  readonly migrations = new MigrationsNamespace(this.http);
+  readonly rules = new RulesNamespace(this.http);
+  readonly mixins = new MixinsNamespace(this.http);
+  readonly generation = new GenerationNamespace(this.http);
+}
+
+export class ModelAccessor {
+  constructor(
+    readonly _name: string,
+    private readonly http: HttpClient
+  ) {}
+
+  async get(version?: number): Promise<S.Model> {
+    const params = version ? { version } : undefined;
+    return this.http.get("/ontology/engine/runs", params);
+  }
+
+  async update(definition: Partial<S.ModelDefinition>): Promise<S.Model> {
+    return this.http.post("/ontology/engine/runs", definition);
+  }
+
+  async delete(force = false): Promise<void> {
+    return this.http.post("/ontology/engine/runs", {
+      action: "delete-model",
+      force,
+    });
+  }
+
+  async relationships(): Promise<{ data: S.RelationshipDefinition[] }> {
+    return this.http.get("/ontology/engine/runs");
+  }
+
+  async addRelationship(
+    definition: S.RelationshipDefinition
+  ): Promise<S.RelationshipDefinition> {
+    const body = S.RelationshipDefinitionSchema.parse(definition);
+    return this.http.post("/ontology/engine/runs", body);
+  }
+
+  async removeRelationship(relationshipId: string): Promise<void> {
+    return this.http.post("/ontology/engine/runs", {
+      action: "delete-relationship",
+      relationshipId,
+    });
+  }
+
+  async validateData(): Promise<{
+    entityType: string;
+    totalChecked: number;
+    violations: unknown[];
+  }> {
+    return this.http.post("/ontology/engine/ontologies/validate");
+  }
+
+  async versions(): Promise<{
+    data: Array<{
+      version: number;
+      createdAt: string;
+      changedBy: string;
+      changesSummary: string;
+      migrationId?: string;
+    }>;
+  }> {
+    return this.http.get("/ontology/engine/runs");
+  }
+}
+
+export class MigrationsNamespace {
+  constructor(private readonly http: HttpClient) {}
+
+  async plan(request: {
+    modelId?: string;
+    changes?: S.ModelDefinition[];
+  }): Promise<S.MigrationPlan> {
+    return this.http.post(
+      "/ontology/engine/ontologies/compare-versions",
+      request
+    );
+  }
+
+  async apply(
+    planId: string,
+    strategy = "zero-downtime"
+  ): Promise<{ id: string; status: string; appliedAt: string }> {
+    return this.http.post("/ontology/engine/runs", { planId, strategy });
+  }
+
+  async rollback(
+    _migrationId: string
+  ): Promise<{ id: string; status: string; rolledBackAt: string }> {
+    return this.http.post("/ontology/engine/runs");
+  }
+
+  async history(opts: { limit?: number; cursor?: string } = {}): Promise<
+    PageResult<{
+      id: string;
+      modelId: string;
+      fromVersion: number;
+      toVersion: number;
+      status: string;
+      createdAt: string;
+    }>
+  > {
+    const raw = await this.http.get("/ontology/engine/runs", opts);
+    return createPageResult(
+      asPagePayload<{
+        id: string;
+        modelId: string;
+        fromVersion: number;
+        toVersion: number;
+        status: string;
+        createdAt: string;
+      }>(raw),
+      (cursor) => this.history({ ...opts, cursor })
+    );
+  }
+}
+
+export class RulesNamespace {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<{ data: S.RuleDefinition[] }> {
+    return this.http.get("/ontology/engine/runs");
+  }
+
+  async create(definition: S.RuleDefinition): Promise<S.RuleDefinition> {
+    const body = S.RuleDefinitionSchema.parse(definition);
+    return this.http.post("/ontology/engine/runs", body);
+  }
+
+  async update(
+    _ruleId: string,
+    definition: Partial<S.RuleDefinition>
+  ): Promise<S.RuleDefinition> {
+    return this.http.post("/ontology/engine/runs", definition);
+  }
+
+  async delete(ruleId: string): Promise<void> {
+    return this.http.post("/ontology/engine/runs", {
+      action: "delete-rule",
+      ruleId,
+    });
+  }
+
+  async evaluate(opts: {
+    entityType?: string;
+    ruleIds?: string[];
+    sample?: number;
+  }): Promise<{ results: unknown[]; summary: unknown }> {
+    return this.http.post("/ontology/engine/ontologies/validate", opts);
+  }
+}
+
+export class MixinsNamespace {
+  constructor(private readonly http: HttpClient) {}
+
+  async list(): Promise<{ data: S.MixinDefinition[] }> {
+    return this.http.get("/ontology/engine/runs");
+  }
+
+  async create(definition: S.MixinDefinition): Promise<S.MixinDefinition> {
+    const body = S.MixinDefinitionSchema.parse(definition);
+    return this.http.post("/ontology/engine/runs", body);
+  }
+}
+
+export class GenerationNamespace {
+  constructor(private readonly http: HttpClient) {}
+
+  async generate(
+    description: string,
+    opts: { context?: { existingModels?: string[] }; substrates?: string[] }
+  ): Promise<{
+    proposal: S.ModelDefinition;
+    confidence: number;
+    reasoning: string;
+  }> {
+    return this.http.post("/ontology/engine/ontologies/generate", {
+      description,
+      ...opts,
+    });
+  }
+
+  async infer(opts: {
+    substrates?: string[];
+    confidence?: "low" | "medium" | "high";
+    merge?: boolean;
+  }): Promise<{ proposals: unknown[] }> {
+    return this.http.post("/ontology/engine/ontologies/infer-classes", opts);
+  }
+
+  async suggestions(
+    opts: { status?: "pending" | "accepted" | "rejected" } = {}
+  ): Promise<{ data: unknown[] }> {
+    return this.http.get("/ontology/engine/runs", opts);
+  }
+
+  async acceptSuggestion(_suggestionId: string): Promise<unknown> {
+    return this.http.post("/ontology/engine/runs");
+  }
+
+  async rejectSuggestion(
+    _suggestionId: string,
+    reason?: string
+  ): Promise<unknown> {
+    return this.http.post("/ontology/engine/runs", {
+      reason,
+    });
+  }
+}