Skip to main content

Concepts API

The Concepts API allows you to manage and execute Vadalog concepts within projects. This is one of the core APIs for working with logical reasoning and data analysis.

Save Concept​

Save or update a concept with Vadalog logic and optional Python scripts.

import prometheux_chain as px

# Define concept logic in Vadalog
concept_logic = """
company("Apple", "Redwood City, CA").
company("Google", "Mountain View, CA").
company("Microsoft", "Redmond, WA").

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

@output("location").
"""

# Save the concept
result = px.save_concept(
    project_id="my_project_id",
    concept_logic=concept_logic
)

Function Signature

def save_concept(
    project_id=None, 
    concept_logic=None, 
    scope="user", 
    python_scripts=None
)

Parameters

ParameterTypeRequiredDescription
project_idstrYesThe project identifier
concept_logicstrYesThe Vadalog logic defining the concept
scopestrNoThe scope of the concept. Defaults to "user"
python_scriptsdictNoDictionary of Python scripts to inject. Keys are script names, values are script content

Returns

The response data from saving the concept.

Example with Python Script Injection​

import prometheux_chain as px

# Define a Python script with proper structure
python_script = """
import json

def main():
    # Simple calculations
    numbers = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
    
    # Calculate basic statistics
    total = sum(numbers)
    average = total / len(numbers)
    maximum = max(numbers)
    minimum = min(numbers)
    
    # Create results as a list of dictionaries (tabular format)
    results = [
        {
            "Numbers": numbers,
            "Total": total,
            "Average": round(average, 2),
            "Maximum": maximum,
            "Minimum": minimum,
            "Count": len(numbers)
        }
    ]
    
    return results
"""

# Define concept logic that uses Python script execution
concept_logic = """
@output("test_python").
test_python(Numbers,Total,Average,Maximum,Minimum,Count) :- python:run("python_script").
"""

# Save the concept with Python script injection
result = px.save_concept(
    project_id="my_project_id",
    concept_logic=concept_logic,
    python_scripts={
        "python_script": python_script
    }
)

Python Script Injection Requirements​

When using Python script injection with save_concept, there are specific requirements that must be followed:

1. Main Function Requirement​

Every Python script must contain a main() function that serves as the entry point:

def main():
    # Your script logic here
    return results

2. Tabular Output Format​

The main() function must return results in a tabular format, as a list of dictionaries:

def main():
    results = [
        {
            "Column1": value1,
            "Column2": value2,
            "Column3": value3
        }
    ]
    return results

3. Concept Head Alignment​

Output column names must match the parameters in the concept head:

# Python script returns:
results = [{"Numbers": [1, 2, 3], "Total": 6, "Average": 2.0}]

# Vadalog concept head must match:
test_python(Numbers, Total, Average) :- python:run("python_script").

4. Standalone Concept Rule​

Python script concepts must be standalone:

# ✅ Correct - standalone Python script concept
@output("my_python_concept").
my_python_concept(Col1, Col2) :- python:run("my_script").

# ❌ Incorrect - cannot combine with other logic
@output("mixed_concept").
mixed_concept(Col1, Col2) :- python:run("my_script"), other_predicate(Col1).

Run Concept​

Execute a concept with specified parameters. This is the main endpoint for running Vadalog logic.

import prometheux_chain as px

# Run a concept with parameters
results = px.run_concept(
    project_id="my_project_id",
    concept_name="location",
    params={"filter_city": "CA"},
    step_by_step=True,
    persist_outputs=True
)

Function Signature

def run_concept(
    project_id=None, 
    concept_name=None, 
    params=None, 
    project_scope="user", 
    step_by_step=False, 
    materialize_intermediate_concepts=False, 
    force_rerun=True, 
    persist_outputs=False
)

Parameters

ParameterTypeRequiredDescription
project_idstrYesThe project identifier
concept_namestrYesThe name of the concept to run
paramsdictNoParameters to pass to the concept execution
project_scopestrNoThe scope of the project. Defaults to "user"
step_by_stepboolNoExecute step by step. Defaults to False
materialize_intermediate_conceptsboolNoMaterialize intermediate concepts. Defaults to False
force_rerunboolNoForce rerun even if results exist. Defaults to True
persist_outputsboolNoPersist the outputs. Defaults to False

Returns

The execution results data.

Response​

{
  "data": {
    "execution_id": "exec_12345",
    "results": [...],
    "execution_time": 1.23,
    "rows_processed": 1500
  },
  "message": "Concept executed successfully",
  "status": "success"
}

List Concepts​

List all concepts in a project.

import prometheux_chain as px

# List all concepts in a project
concepts = px.list_concepts(project_id="my_project_id")
print(f"Available concepts: {concepts}")

Function Signature

def list_concepts(
    project_id=None, 
    project_scope="user"
)

Parameters

ParameterTypeRequiredDescription
project_idstrYesThe project identifier
project_scopestrNoThe scope of the project. Defaults to "user"

Returns

List of concept information dictionaries.

Cleanup Concepts​

Delete concepts from a project.

import prometheux_chain as px

# Clean up all concepts in a project
result = px.cleanup_concepts(project_id="my_project_id")

# Clean up all user concepts
result = px.cleanup_concepts()

Function Signature

def cleanup_concepts(
    project_id=None, 
    project_scope="user"
)

Parameters

ParameterTypeRequiredDescription
project_idstrNoThe project identifier. If None, cleans up all concepts for the user
project_scopestrNoThe scope of the project. Defaults to "user"

Rename Concept​

Rename an existing concept.

import prometheux_chain as px

# Rename a concept
result = px.rename_concept(
    project_id="my_project_id",
    old_name="old_concept_name",
    new_name="new_concept_name"
)

Complete Workflow Example​

import prometheux_chain as px
import os

# Set up authentication and configuration
os.environ['PMTX_TOKEN'] = 'my_pmtx_token'
px.config.set('JARVISPY_URL', "https://api.prometheux.ai/jarvispy/my-org/my-user")

# Create a project
project_id = px.save_project(project_name="concept_demo")

# Define and save a concept
concept_logic = """
company("Apple", "Redwood City, CA").
company("Google", "Mountain View, CA").
company("Microsoft", "Redmond, WA").

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

@output("location").
"""

px.save_concept(project_id=project_id, concept_logic=concept_logic)

# List all concepts
concepts = px.list_concepts(project_id=project_id)
print(f"Available concepts: {concepts}")

# Run the concept
results = px.run_concept(project_id=project_id, concept_name="location")
print(f"Results: {results}")

# Clean up when done
px.cleanup_concepts(project_id=project_id)