Overview

Ontologies in Praxos define the structure and types of entities that your system can recognize and extract from data sources. They use Pydantic models to create type-safe schemas that guide entity extraction, validation, and relationship mapping.

SyncOntology Properties

PropertyTypeDescription
idstringUnique identifier for the ontology
namestringName of the ontology
descriptionstringDescription of the ontology

Creating Ontologies

Basic Ontology Creation

from praxos_python import SyncClient
from pydantic import BaseModel, Field
from typing import Optional

client = SyncClient(api_key="your-api-key")

# Define your entity schemas
class Person(BaseModel):
    name: str = Field(description="Full name of the person")
    age: Optional[int] = Field(description="Age in years")
    email: Optional[str] = Field(description="Email address")

class Company(BaseModel):
    name: str = Field(description="Company name")
    industry: Optional[str] = Field(description="Industry sector")
    founded: Optional[int] = Field(description="Year founded")

# Create the ontology
ontology = client.create_ontology(
    name="business-entities",
    description="Core business entity definitions",
    schemas=[Person, Company]
)

print(f"Created ontology: {ontology.id}")

Advanced Schema Definitions

from pydantic import BaseModel, Field, validator
from typing import Optional, List
from datetime import datetime

class Contact(BaseModel):
    name: str = Field(description="Contact name")
    phone: Optional[str] = Field(description="Phone number")
    email: Optional[str] = Field(description="Email address")
    
    @validator('email')
    def validate_email(cls, v):
        if v and '@' not in v:
            raise ValueError('Invalid email format')
        return v

class Project(BaseModel):
    title: str = Field(description="Project title")
    status: str = Field(description="Project status", default="active")
    budget: Optional[float] = Field(description="Project budget in USD")
    team_size: Optional[int] = Field(description="Number of team members")
    tags: Optional[List[str]] = Field(description="Project tags")

class Meeting(BaseModel):
    title: str = Field(description="Meeting title")
    participants: Optional[List[str]] = Field(description="List of participant names")
    duration_minutes: Optional[int] = Field(description="Meeting duration in minutes")
    action_items: Optional[List[str]] = Field(description="List of action items")

# Create a comprehensive project management ontology
project_ontology = client.create_ontology(
    name="project-management",
    description="Ontology for project management entities",
    schemas=[Contact, Project, Meeting]
)

Retrieving Ontologies

Get All Ontologies

# List all ontologies in your account
ontologies = client.get_ontologies()

for ontology in ontologies:
    print(f"Ontology: {ontology.name} (ID: {ontology.id})")
    print(f"Description: {ontology.description}")

Get Specific Ontology

# Retrieve by ID
ontology = client.get_ontology(id="onto-123abc")

# Retrieve by name
ontology = client.get_ontology(name="business-entities")

print(f"Found ontology: {ontology.name}")

Using Ontologies with Environments

Associating Ontologies with Environments

# Create an environment with specific ontologies
environment = client.create_environment(
    name="customer-analysis",
    description="Environment for analyzing customer data",
    ontologies=[ontology]  # Can pass SyncOntology objects or ID strings
)

# Or use ontology IDs directly
environment = client.create_environment(
    name="customer-analysis",
    ontologies=["onto-123abc", "onto-456def"]
)

Best Practices

Schema Design Guidelines

  1. Use Descriptive Field Names: Choose clear, unambiguous field names
  2. Add Comprehensive Descriptions: Field descriptions guide entity extraction
  3. Use Optional Fields Wisely: Mark fields as Optional when they may not always be present
  4. Validate Critical Fields: Use Pydantic validators for important data constraints
class Customer(BaseModel):
    # Good: Clear, descriptive name
    full_name: str = Field(description="Customer's complete legal name")
    
    # Good: Optional with clear description
    annual_revenue: Optional[float] = Field(
        description="Annual revenue in USD, if available"
    )
    
    # Good: Constrained field with validation
    customer_tier: str = Field(
        description="Customer tier: bronze, silver, gold, or platinum",
        default="bronze"
    )
    
    @validator('customer_tier')
    def validate_tier(cls, v):
        allowed_tiers = ['bronze', 'silver', 'gold', 'platinum']
        if v.lower() not in allowed_tiers:
            raise ValueError(f'Tier must be one of: {", ".join(allowed_tiers)}')
        return v.lower()

Ontology Organization

  1. Keep Related Entities Together: Group logically related schemas in the same ontology
  2. Use Meaningful Names: Choose ontology names that clearly indicate their purpose
  3. Document Your Ontologies: Provide detailed descriptions explaining the ontology’s scope
# Good: Focused, well-organized ontology
financial_ontology = client.create_ontology(
    name="financial-entities",
    description="Core financial entities for accounting and reporting",
    schemas=[Transaction, Account, Invoice, Payment]
)

# Good: Clear separation of concerns
hr_ontology = client.create_ontology(
    name="human-resources",
    description="Employee and organizational structure entities",
    schemas=[Employee, Department, Position, Benefit]
)

Error Handling

from praxos_python.exceptions import APIError, APIKeyInvalidError

try:
    ontology = client.create_ontology(
        name="test-ontology",
        schemas=[Person, Company]
    )
except APIKeyInvalidError:
    print("Invalid API key provided")
except APIError as e:
    print(f"Failed to create ontology: {e.message}")
except ValueError as e:
    print(f"Invalid schema definition: {e}")
  • Client - Learn about the SyncClient and basic setup
  • Environment - Understand how ontologies work with environments
  • Source - See how ontologies guide data processing