Prometheux Chain

Description

Prometheux Chain is a Python SDK designed to help you create, evolve, and deploy ontologies with ease. The SDK offers the following capabilities:

• Data Ingestion: Seamlessly integrate data from various sources, including databases and files.
• Reasoning & Knowledge Augmentation: Perform logical reasoning to derive new insights and augment your existing knowledge base.
• Explainability: Gain clear explanations of the results generated by the system.

For more information refer to the documentation

Features

• Supports a wide range of data sources.
• Built-in reasoning engine for deriving new knowledge.
• Easy-to-understand explanations for enhanced interpretability.
• Ready-to-use configurations for fast deployment.

Installation

Requirements

• Python 3.9 or higher (Python 3.13 recommended)

Install Using pip

1. Set Up a Virtual Environment (recommended):

python3 -m venv myenv
source myenv/bin/activate  # On Windows: myenv\Scripts\activate

2. Install the SDK via pip:

pip install --upgrade prometheux-chain

Usage

This guide demonstrates how to get started with the Prometheux Chain SDK. The example below outlines a typical workflow, including creating an ontology, defining concept logic, and running concepts to generate results.

Workflow

Import the prometheux_chain

import prometheux_chain as px
import os

Define the PMTX_TOKEN environment variable for authentication

os.environ['PMTX_TOKEN'] = 'my_pmtx_token'

Configure the backend connection using your Prometheux account

px.config.set('JARVISPY_URL', "https://platform.prometheux.ai/jarvispy/'my_organization'/'my_username'")

Create a new ontology

ontology_id = px.save_ontology(ontology_name="test_ontology")

Define concept logic using Vadalog syntax and save it

definition = """
company("Apple", "Redwood City, CA").
company("Google", "Mountain View, CA").
company("Microsoft", "Redmond, WA").
company("Amazon", "Seattle, WA").
company("Facebook", "Menlo Park, CA").
company("Twitter", "San Francisco, CA").
company("LinkedIn", "Sunnyvale, CA").
company("Instagram", "Menlo Park, CA").

location(Location) :- company(_,Location).

@output("location").
"""
px.save_concept(ontology_id=ontology_id, definition=definition)

Run the concept to generate results

px.run_concept(ontology_id=ontology_id, concept_name="location")

Fetch the produced facts

results = px.fetch_results(ontology_id=ontology_id, output_predicate="location")

Domains

The SDK exposes a flat, function-based API (import prometheux_chain as px) covering the user-facing JarvisPy backend:

• Ontologies — save_ontology, list_ontologies, load_ontology, copy_ontology, export_ontology / import_ontology, export_workspace / import_workspace, list_templates, import_template, create_ontology_from_context, create_snapshot, list_snapshots, restore_snapshot, delete_snapshot.
• Data sources — connect_sources, list_sources, infer_schema, list_sheets, list_demo_sources, refresh_sources, preview_datasource, all_pairs_join, cleanup_sources.
• Files (disk/) — upload_file, list_files, make_directory, delete_files, move_file, download_file.
• Concepts — save_concept, rename_concept, run_concept, run_concept_stream, list_concepts, reorder_concepts, fetch_results, search_results, llm_analysis, download_concept, generate_concept_description, get_concept_description, get_execution_status, get_execution_statuses, cleanup_concepts.
• Knowledge graphs — visualize_concept_lineage, build_graph, list_graph_functions, run_graph_analytics.
• Ontology schema — save_ontology_schema, load_ontology_schema, update_concept_ontology_schema_type, add_to_lineage, import_owl.
• Knowledge / context layer — list_context_notes, create_context_note, create_context_notes_from_file, get_context_note, update_context_note, delete_context_note, search_context_notes, auto_seed, interview_template, submit_interview, onboarding_status, ontology_text.
• Agent — agent_chat (streaming), agent_reset.
• Sharing — create_share, revoke_share, update_share_role, list_shares, list_inbox, accept_share, leave_share, sync_inbox.
• Apps — list_all_apps, list_apps, get_app, save_app, delete_app.
• Schedules — create_policy, list_policies, get_policy, update_policy, delete_policy, trigger_policy, get_run_history.
• Alerts — get_alert_history, reprocess_alert.
• Chat history — list_sessions, get_session, rename_session, delete_session.
• Compute — check_compute_availability.
• Users / account — save_user_config, load_user_config, get_role, list_llm_models, get_usage_status, get_login_activity.
• Auth / tokens — issue_token, list_tokens, revoke_token, revoke_specific_token, revoke_all_tokens.
• Vadalog authoring — analyze_program, build_bind, parse_binds, evaluate_program.
• Vadalingo translation — translate_nl_to_vadalog, translate_sql_to_vadalog, translate_rdf_to_vadalog, translate_owl_to_vadalog.

Optional configuration

Some recipient-side sharing flows require a Supabase token. Set it via the SUPABASE_TOKEN environment variable (or px.config) and it is attached automatically as the X-Supabase-Token header when present.

Streaming

A few endpoints stream results instead of returning a single response. These return Python generators you iterate over.

Chat with the Vadalog AI agent (NDJSON stream)

for event in px.agent_chat(ontology_id=ontology_id, message="What does this ontology do?"):
    if event.get("type") == "content":
        print(event["data"]["chunk"], end="")

Run a concept with live status updates (WebSocket stream)

WebSocket streaming requires the websocket-client dependency (installed automatically with the SDK).

for event in px.run_concept_stream(ontology_id=ontology_id, concept_name="location"):
    print(event.get("event"), event.get("data"))
    # iteration ends after the terminal "complete" or "error" event

Auto-seed the context layer from connected data sources (NDJSON stream)

for event in px.auto_seed(scope="project", scope_id=ontology_id):
    print(event)

Tokens

Issue and manage API tokens programmatically:

token = px.issue_token(name="ci-bot", expires_in_minutes=60)
print(token["token"])   # the raw JWT — shown only once
px.list_tokens()
px.revoke_specific_token(token["jti"])

For Maintainers

Releasing a New Version

Pushing a v* tag publishes to PyPI — see .github/workflows/publish.yml. Nothing is built from a laptop, so what customers install is always a commit that was merged and reviewed.

# 1. Bump the version. This is the only place it lives: setup.py stamps it into
#    the package metadata, and prometheux_chain.__version__ reads it back out.
echo "0.3.2" > version.txt

# 2. Commit it and get it onto main (via a PR, as usual)
git add version.txt
git commit -m "Release version 0.3.2"

# 3. Tag the merged commit and push the tag — this triggers the release
git checkout main && git pull
git tag v0.3.2
git push origin v0.3.2

The workflow refuses to publish if the tag and version.txt disagree, or if the tagged commit has not reached main. It then imports the package, builds, and uploads. A version already on PyPI fails the upload rather than being skipped quietly.

One-time PyPI setup. The workflow authenticates with trusted publishing rather than a stored API token, so it must be registered once by a PyPI owner of the project: prometheux-chain → Manage → Publishing → add a GitHub publisher with owner prometheuxresearch, repository prometheux-chain, workflow publish.yml, no environment. Until that exists the upload step fails with an OIDC error; nothing else in the workflow is affected.

deploy.sh predates this workflow and uploads straight from the working tree, bypassing every check above. Prefer the tag.

Access to Prometheux Backend

The Prometheux backend is required to use this SDK. To request access:

• 📧 Email: davben@prometheux.co.uk, teodoro.baldazzi@prometheux.co.uk, or support@prometheux.co.uk
• 🌐 Website: https://www.prometheux.ai

License

BSD 3-Clause License — see LICENSE file for details.

About Prometheux

Prometheux is an ontology native data engine that processes data anywhere it lives. Define ontologies once and unlock knowledge that spans databases, warehouses, and platforms—built on the Vadalog reasoning engine.

Key capabilities:

• Connect: Query across Snowflake, Databricks, Neo4j, SQL, CSV, and more without ETL or vendor lock-in
• Think: Replace 100+ lines of PySpark/SQL with simple declarative logic. Power graph analytics without GraphDBs
• Explain: Full lineage & traceability with deterministic, repeatable results. Ground AI in structured, explainable context

Exponentially faster and simpler than traditional approaches. Learn more at prometheux.ai.

Support

For issues, questions, or access requests:

• Homepage: https://www.prometheux.ai
• PyPI: https://pypi.org/project/prometheux-chain/
• Email: davben@prometheux.co.uk, teodoro.baldazzi@prometheux.co.uk, or support@prometheux.co.uk
• Documentation: https://docs.prometheux.ai/integrations/python-sdk
• Issues: GitHub Issues

Related Projects

• Prometheux MCP — MCP client for AI agents
• Vadalog Extension — JupyterLab extension for Vadalog
• Vadalog Jupyter Kernel — Jupyter kernel for Vadalog