Skip to main content

twa is a Python wrapper for TheWorldAvatar project.

Project description

TheWorldAvatar (twa)

twa is a Python wrapper for TheWorldAvatar project. It expands on the TWA's Java functions with Python-native capabilities.

What is twa

The code is heavily based on the py4j package, which enables Python programs running in a Python interpreter to dynamically access Java objects in a Java Virtual Machine. It has a precedent python package, py4jps, which is now deprecated.

To get started, see the Quick start below or follow our tutorial.

Installation

To install twa, use the following command: pip install twa

You also need to install a Java Runtime Environment version 11:

  • [Recommended] If you are using Linux (or Windows Subsystem for Linux): apt install openjdk-11-jdk-headless
  • If you are using Windows machine: please follow the tutorial here

Quick start

from __future__ import annotations

###############################################
# Spin up a docker container for triple store #
###############################################
import docker
# Connect to Docker using the default socket or the configuration in your environment:
client = docker.from_env()

# Run Blazegraph container
# It returns a Container object that we will need later for stopping it
blazegraph = client.containers.run(
    'ghcr.io/cambridge-cares/blazegraph:1.1.0',
    ports={'8080/tcp': 9999}, # this binds the internal port 8080/tcp to the external port 9998
    detach=True # this runs the container in the background
)


#############################
# Instantiate sparql client #
#############################
from twa.kg_operations import PySparqlClient

# Define the SPARQL endpoint URL for the Blazegraph instance
sparql_endpoint = 'http://localhost:9999/blazegraph/namespace/kb/sparql'

# Create a SPARQL client to interact with the Blazegraph endpoint
sparql_client = PySparqlClient(sparql_endpoint, sparql_endpoint)


################################################
# Upload an ontology from an internet location #
################################################
# Example: Upload the PROV ontology from the web
prov_ttl = 'https://www.w3.org/ns/prov.ttl'
from rdflib import Graph

# Parse the ontology and upload it to the triple store
sparql_client.upload_graph(Graph().parse(prov_ttl))


########################
# Perform some queries #
########################
# Example query: Retrieve subclasses of prov:Agent
results = sparql_client.perform_query(
    """
    prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>
    prefix prov: <http://www.w3.org/ns/prov#>
    select *
    where {?agent rdfs:subClassOf prov:Agent}
    """
)
print(results)
# Expected output:
# > [{'agent': 'http://www.w3.org/ns/prov#Organization'},
# > {'agent': 'http://www.w3.org/ns/prov#Person'},
# > {'agent': 'http://www.w3.org/ns/prov#SoftwareAgent'}]


#########################
# Create a new ontology #
#########################
from twa.data_model.base_ontology import BaseOntology, BaseClass, TransitiveProperty, ObjectProperty, DatatypeProperty
from twa.data_model.iris import TWA_BASE_URL
from typing import ClassVar, Optional

# Define a minimal agent ontology
class MinimalAgentOntology(BaseOntology):
    base_url: ClassVar[str] = TWA_BASE_URL
    namespace: ClassVar[str] = 'mao'
    owl_versionInfo: ClassVar[str] = '0.0.1'
    rdfs_comment: ClassVar[str] = 'A minimal agent ontology'

# Define classes and properties for the ontology
class Agent(BaseClass):
    rdfs_isDefinedBy = MinimalAgentOntology
    name: Name[str]
    hasGoal: HasGoal[Goal]
    # Like native Pydantic, you can define optional fields (properties)
    actedOnBehalfOf: Optional[ActedOnBehalfOf[Agent]] = None

class Goal(BaseClass):
    rdfs_isDefinedBy = MinimalAgentOntology
    priority: Priority[str]

Name = DatatypeProperty.create_from_base('Name', MinimalAgentOntology, 1, 1)
"""
This is equivalent to:

class Name(DatatypeProperty):
    rdfs_isDefinedBy = MinimalAgentOntology
    owl_minQualifiedCardinality = 1
    owl_maxQualifiedCardinality = 1
"""
Priority = DatatypeProperty.create_from_base('Priority', MinimalAgentOntology, 1, 1)

HasGoal = ObjectProperty.create_from_base('HasGoal', MinimalAgentOntology)

# Another way of defining properties
class ActedOnBehalfOf(TransitiveProperty):
    rdfs_isDefinedBy = MinimalAgentOntology


#######################################
# Export the TBox to the triple store #
#######################################
# Export the ontology definition (TBox) to the triple store
MinimalAgentOntology.export_to_triple_store(sparql_client)


####################################
# Instantiate some objects as ABox #
####################################
# Create instances (ABox) of the ontology classes
machine_goal = Goal(
    rdfs_comment='continued survival',
    priority='High'
)
machine = Agent(
    name='machine',
    hasGoal=machine_goal
)
smith_goal = Goal(
    rdfs_comment='keep the system in order',
    priority='High'
)
agent_smith = Agent(
    name='smith',
    actedOnBehalfOf=machine,
    hasGoal=smith_goal
)

# Push the instances to the knowledge graph
agent_smith.push_to_kg(sparql_client, -1)


########################
# Perform some queries #
########################
# Retrieve all instances of the Agent class from the knowledge graph
agents = Agent.pull_all_instances_from_kg(sparql_client, -1)

# Once the objects are pulled, the developer can access information in a Python-native format
# Example: Print out the goals of each agent
for agent in agents:
    print(f'agent {agent.name} has goal: {agent.hasGoal}')
# Expected output:
# > agent {'smith'} has goal: {Goal(rdfs_comment='keep the system in order', ...)}
# > agent {'machine'} has goal: {Goal(rdfs_comment='continued survival', ...)}

Documentation

The documentation for twa can be found here.

Issues? Feature requests?

Submit an issue with a label python-wrapper.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

twa-0.0.5.tar.gz (59.9 MB view details)

Uploaded Source

Built Distribution

twa-0.0.5-py3-none-any.whl (60.0 MB view details)

Uploaded Python 3

File details

Details for the file twa-0.0.5.tar.gz.

File metadata

  • Download URL: twa-0.0.5.tar.gz
  • Upload date:
  • Size: 59.9 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.4

File hashes

Hashes for twa-0.0.5.tar.gz
Algorithm Hash digest
SHA256 2f5bd24ba9dff16b957eca96a21845597499bc52e077fb9183fa53cec0d4b8b1
MD5 7afbaae3e27581a8a943316384250e7f
BLAKE2b-256 cf9c840426fa0aa392c925ff96bdaca2670120dc8ac3c9d26901d518cc1c95c4

See more details on using hashes here.

File details

Details for the file twa-0.0.5-py3-none-any.whl.

File metadata

  • Download URL: twa-0.0.5-py3-none-any.whl
  • Upload date:
  • Size: 60.0 MB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.10.4

File hashes

Hashes for twa-0.0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 9d9feaa4ed2b8507f23c5d047b6d0fe0ef9c10bb6bedbfbc8476a81b741278d5
MD5 cb1132498cf5f74a12689b2727f94d96
BLAKE2b-256 697083b2f2c4c5af9ee44d3189dfab53bf7ab4bc3ea0c70f4d76130c24fad239

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page