Authoring a workspace

A px workspace is one git repo holding a shared context vault plus one or more ontologies. This page is the reference for the files that describe an ontology’s lineage.

Workspace anatomy

my-workspace/
  prometheux.workspace.yaml     # lists the shared context vault + ontologies
  .px/schemas/                  # bundled JSON Schemas ($schema-referenced by files)
  context/                      # workspace-global context (see Context as code)
  ontologies/
    credit-risk/
      prometheux.yaml           # ontology manifest (id, name, scope + section paths)
      concepts/
        customers.vadalog       # concept body (per-kind extension)
        customers.meta.yaml     # envelope: conceptType, outputPredicate, binds, …
        revenue.sql             # sql source (transpiled server-side)
        enrich.py               # python script
        summarize.llm.md        # llm prompt (frontmatter config + prompt body)
        relevant.context.yaml   # context concept (note selection)
      datasources/
        snowflake_prod.yaml     # connection or file spec
      ontology/
        schema.yaml             # node/edge graph
      apps/
        credit_risk.app.yaml    # AppDefinition v2
      context/                  # this ontology's project-scoped context
      files/                    # local datasource files (e.g. from `pull --with-files`)

Every YAML/manifest carries a $schema reference to a file under .px/schemas/, so any editor’s language server gives you autocomplete and validation as you type. The schema is the single source of truth px validate enforces.

The manifests

`prometheux.workspace.yaml`

schemaVersion: 1
workspace:
  name: acme-data
context: ./context            # the shared, global-scope context vault
ontologies:
  - ./ontologies/credit-risk
  - ./ontologies/fraud-detection

`ontologies/<slug>/prometheux.yaml`

schemaVersion: 1
ontology:
  id: 1d22942b9a0        # server ontology id; absent on a brand-new ontology (apply fills it)
  name: Credit Risk
  scope: user            # user | organization
concepts: ./concepts
datasources:
  - ./datasources/snowflake_prod.yaml
ontologySchema: ./ontology/schema.yaml
apps: ./apps
context: ./context

apply writes the assigned id back into this file after creating an ontology — commit it, so re-apply targets the same ontology. If the id is lost, apply reconciles by name (adopts a single existing same-name ontology in scope rather than duplicating), so a unique ontology name makes recovery reliable.

Concept kinds

A concept is a body file (concepts/<predicate>.<ext>) plus, for most kinds, a <predicate>.meta.yaml envelope. The body extension carries the language you authored — don’t rename everything to .vadalog.

Kind	Body file	`conceptType`	Notes
logic	`.vadalog`	`logic`	native Vadalog rules
sql	`.sql`	`sql`	SQL source; server transpiles to Vadalog on apply
cypher	`.cypher`	`cypher`	Cypher source; transpiled on apply
python	`.py`	`python`	a Python script (leaf node, never spliced)
llm	`.llm.md`	`llm`	prompt template + `llmConfig` frontmatter
context	`.context.yaml`	`context`	note selection (static or dynamic)

The `.meta.yaml` envelope

conceptType: logic
outputPredicate: customer      # the concept's output predicate (its lineage node name)
group: ingest                  # optional grouping
binds:
  input:
    - predicate: source_customers   # the predicate used in the body
      datasource: snowflake_prod    # a datasources/ file name
      table_name: RAW.CUSTOMERS     # optional, for DB tables
  output: []                        # empty/unbound → materialized by the engine
fields:
  - { name: Id, type: string }
  - { name: Name, type: string }

Bind a predicate in binds.input only when it comes from a datasource. A predicate produced by another concept is a derived edge — never bind it (see below).

logic

Native Vadalog. customers.vadalog:

customer(Id, Name, Country) :- source_customers(Id, Name, Country).

sql / cypher

Store the source query you wrote; the server transpiles it to Vadalog on apply, and pull recovers the source (not the transpiled form). revenue.sql:

SELECT customer_id, SUM(amount) AS revenue FROM orders GROUP BY customer_id

The .meta.yaml uses conceptType: sql (or cypher).

python

A Python script — a leaf node, never parsed as Vadalog. enrich.py plus a enrich.meta.yaml with conceptType: python.

llm

A prompt template with llmConfig frontmatter and the prompt as the body. summarize.llm.md:

---
conceptType: llm
outputPredicate: customer_summary
llmConfig:
  provider: anthropic
  model: claude-sonnet-4-6
  output_columns: [Id, summary]
---
Summarize each customer's risk profile in one sentence, given {{ Id }} and their attributes.

context

A note selection — static (pin note paths) or dynamic (retrieve by query). relevant.context.yaml:

conceptType: context
outputPredicate: relevant_policy
contextMode: dynamic
query: "credit-risk scoring policy"

The derived graph

You never hand-write lineage edges. A concept’s Vadalog head/body predicates are the edges:

% risk_score.vadalog — references `customer`, which another concept outputs
risk(Id, Score) :- customer(Id, _, Country), country_risk(Country, Score).

Because customer and country_risk are produced by other concepts, px plan reconstructs the edge customer → risk automatically. There is no binds.input entry for them — only datasource-backed predicates get bound. Changing a concept’s rules invalidates its results and cascades to everything downstream; plan renders that cascade before you apply.

Datasources

Datasource specs live in datasources/*.yaml. Secrets are always ${ENV_VAR} placeholders, resolved from the environment at apply and never written to files.

Connection
Local file
Object store (S3)

Databases (postgres / mariadb / clickhouse / teradata / snowflake / …). Author one table per file so the concept binds it unambiguously (a DB connect returns the whole group):

name: pg_companies
type: postgresql
host: databases.prometheux.ai
port: 5432
username: prometheux
password: ${PG_PASSWORD}
database: prometheux
tables:
  - prometheux.public.companies

csv / parquet / json / excel. apply uploads the file to the workspace disk, then connects it (requires the Data Manager service):

name: customers_csv
type: csv
file: ../data/customers.csv
diskPath: uploads         # optional subdir under disk/

Connected in place, no upload. Put the full path (bucket and sub-dir) in host, and do not set database:

name: s3_air_routes
type: csv
host: s3a://my-bucket/airports    # full path — bucket AND sub-dir
port: 0
s3aAccessKey: ${S3_ACCESS_KEY}
s3aSecretKey: ${S3_SECRET_KEY}
useHeaders: "true"
tables:
  - air-routes-nodes.csv

For S3, splitting the path (host: s3a://my-bucket, database: airports) makes the connect succeed but drops the sub-dir from the stored bind — the concept then fails at run time with PATH_NOT_FOUND. Always put the whole path in host.

A concept reads a datasource through an input bind in its .meta.yaml (binds.input, referencing the datasource name). A datasource already on the account is reused (matched by type/host/port/table), not re-connected — so repeated applies never pile up duplicate rows.

Ontology and apps

ontologySchema (ontology/schema.yaml) — an entity/edge graph in the save_ontology_schema shape. The platform ontology view is drawn from concept lineage, so an ontology with a schema graph but no concepts renders empty; px validate warns about this.
apps/*.app.yaml — an AppDefinition v2. App project.id references are retargeted automatically when an ontology is recreated on another account.

Guardrails

Never put secrets in files — reference them as ${ENV_VAR}.
Never hand-write lineage edges, and never bind a predicate that another concept produces.
One table per datasource file for DB connections.
v1 concepts refer only within their own ontology — the only cross-ontology sharing is scope: global context.

Next: Context as code or the Command reference.

Introduction

Get Started

Platform

Integrations

Examples

Vadalog Reference

Resources

Authoring a workspace

Workspace anatomy

The manifests

`prometheux.workspace.yaml`

`ontologies/<slug>/prometheux.yaml`

Concept kinds

The `.meta.yaml` envelope

logic

sql / cypher

python

llm

context

The derived graph

Datasources

Ontology and apps

Guardrails

​Workspace anatomy

​The manifests

​prometheux.workspace.yaml

​ontologies/<slug>/prometheux.yaml

​Concept kinds

​The .meta.yaml envelope

​logic

​sql / cypher

​python

​llm

​context

​The derived graph

​Datasources

​Ontology and apps

​Guardrails

Workspace anatomy

The manifests

`prometheux.workspace.yaml`

`ontologies/<slug>/prometheux.yaml`

Concept kinds

The `.meta.yaml` envelope

logic

sql / cypher

python

llm

context

The derived graph

Datasources

Ontology and apps

Guardrails