Skip to content

Ontology Functions, Actions, and three Suite Apps

Research note for the Palantir-aligned Ontology Logic layer in openKMS: three Suite Apps, PostgreSQL-backed Functions, and the ontology-function-service (ofs) executor.

Related: Ontology · Ontology Functions · Ontology SDK · Object Explorer · ontology_manager_alignment.md

Executive summary

Area Palantir analogue openKMS choice
Schema governance Ontology Manager Ontology Manager (/ontology-manager)
Instance browse + Cypher Object Explorer Object Explorer (/object-explorer)
Python Logic authoring Code Repositories / Functions Function Editor (/function-editor)
Function storage Foundry versioned repos PostgreSQL ontology_functions + versions
Execution Restricted serverless ofs subprocess on :8105
Author + caller SDK @osdk/client (+ optional generated ontology SDK) openkms_functions.Client (string api names; no generated marker package)
Entry registration @function / export default @function + DB entrypoint

Core Palantir lesson: function authors and external apps share one client language (client(Entity).method(...)). Only construction differs (injected vs explicit token).

Palantir OSDK model (two layers)

Palantir splits platform Client (@osdk/client) from an optional generated ontology SDK (typed definitions). openKMS currently implements only the platform Client as openkms_functions, with string api names:

flowchart TB
  subgraph platform [Platform package]
    ClientPkg["openkms_functions.Client"]
    Helpers["@function / create_edit_batch"]
  end
  subgraph authors [Function runtime]
    Decorated["@function def fn(input, client)"]
  end
  subgraph external [External scripts / apps]
    Explicit["Client(base_url, token)"]
  end
  ClientPkg --> authors
  ClientPkg --> external
  Helpers --> authors
Concern Palantir openKMS
Register entry @function(api_name=…) / TS default export @function + entrypoint column
Ontology read client(Aircraft).fetchOne client("Employee").fetch_one / .search
Compose functions client(query).executeFunction client("query").execute_function
Dependencies @Uses / resource imports @function(uses=[…]) publish gate
Writes Edit batch → Action create_edit_batch (apply via Actions)

execute as a function name is not required by Palantir; openKMS keeps it as the default entrypoint for templates and legacy code.

Three App responsibilities

Ontology Manager

  • Groups, object/link types, datasets
  • Functions: registry, publish, Observability tab
  • Actions: types, execute, logs

Object Explorer

  • Instance browse / CRUD; can trigger Actions

Function Editor

  • Author @function Python code, Live Preview, published-queries sidebar
  • Publish only in Manager

Backend structure (clean architecture)

Layer Module
HTTP Thin routers in app/api/ontology_*.py
Shared deps app/api/ontology/deps.py — token, api_name, JWT user
Services function_service.py, execution_service.py
Runtime function_runtime.py → ofs HTTP
Validation function_templates.py, input_schema.py

Author SDK

Prefer string api names (no generated import required):

from openkms_functions import Client, function, create_edit_batch

@function(uses=["helloGreeting"])
def execute(input: dict, client: Client) -> dict:
    greeting = client("helloGreeting").execute_function({"name": input.get("name", "")})
    return {"greeting": greeting}

openKMS does not ship a generated ontology marker package; Palantir’s generated OSDK layer is deferred.

Legacy def execute(input, ctx) still works (deprecation warning).

Composition safety: max call depth 5; X-OpenKMS-Function-Call-Stack cycle detection.

Execution model

sequenceDiagram
  participant FE as Function Editor
  participant BE as Backend
  participant OFS as ofs
  participant PG as PostgreSQL

  FE->>BE: POST execute
  BE->>PG: load version + entrypoint
  BE->>BE: input_schema + call stack checks
  BE->>OFS: POST /execute
  OFS->>OFS: @function resolve + Client inject
  OFS->>BE: Client HTTP (token)
  OFS-->>BE: result
  BE->>PG: audit execution
  BE-->>FE: output

Phasing status

Phase Status
Three Apps + PG + ofs MVP Done
Service-layer refactor + tests Done
@function + unified Client + composition Done
Codegen / generated ontology marker SDK Not shipped — string api names on openkms_functions.Client only
Editor hooks / queries sidebar / Observability tab Done
External same-package Client Done (docs + path)
Edit batch apply via Actions Shipped for no-dataset types: queue in object_instances + same-request Neo4j sync; see Manager alignment — Action write-back
Dataset/Neo4j Action object_id Deferred (Action execute resolves Explorer-created instance ids; modify apply ships for those)
Web API function source / TS runtime / Dev Console apps Out of scope
Domain ontologies (e.g. Tushare market Stock/Watchlist) Not product — tenant DIY via Manager / openkms-skill

Non-goals

  • Generic Git multi-repo IDE
  • Pipeline / Spark in Function Editor
  • Arbitrary pip install in user functions
  • TypeScript Function runtime
  • Per-app Developer Console SDK subsets