Skip to content

index.rst

Latest commit

 

History

History
205 lines (133 loc) · 6.67 KB

index.rst

File metadata and controls

205 lines (133 loc) · 6.67 KB

Welcome to hydra-python-agent's documentation!

hydra-python-agent is a smart Hydra client implemented in Python which works with hydrus. Reference implementation is Heracles.ts. Smart clients are generic automated clients that establish resilient connected data networks leveraging knowledge graphs.

agent module

The agent is used in order to:
  1. Provide a seamless Client that can be used to communicate with Hydra APIs.
  2. Cache metadata from the Hydra server it connects to, to allow querying on the client-side.
  3. Maintain a syncrhonization mechanism which makes sure cached resources are consistent.
  4. The graph can be queried using OpenCypher.

The agent module contains a main Agent class. The agent module uses a redis caching layer to store the generated apidoc and allow efficient querying. This class inherits classes from the socketio module and the Session class from the requests module. This class is first initialized with the main entrypoint url. (Example) In this case, the entrypoint_url is "http://localhost:8080/serverapi". A connection to the redis server is initialized using the redis modules (present in the redis_core files) and a connection with the hydrus server is established at the entrypoint url provided using socketio.

The Agent class has various functions. Some commonly used functions are explained below:

  1. fetch_apidoc()
    This function is used to generate the apidoc for the entrypoint_url initialized and the name of the api which is extracted from the entrypoint_url. This apidoc is generated by passing the apidoc present in hydrus through the doc_maker module from hydra-python-core.
  2. get()
    This function is used to handle a GET request to the url mentioned as a parameter. The function returns an apidoc for the respective resource from the redis graph in a JSON format.
  3. post()
    This function is used to handle a POST request to the url mentioned as a parameter. It is used to update the resource at the specified url.
  4. put()
    This function is used to handle a PUT request to the url mentioned as a parameter. It is used to add a resource at the specified url.

The final goal is to create a Client that can connected to multiple hydrus servers and operate between them while caching information in a graph-based database(Redis). This should enable the client to have an "aggregated view" of the connected network (the network of all the servers it connects to) and make complex sematic queries to it.

Usage

For the installation process, click here

  1. Initializing the Agent:
from hydra_agent.agent import Agent
agent = Agent("http://localhost:8080/serverapi")
  1. To add a new resource using a PUT request:

Syntax:

agent.put("http://localhost:8080/serverapi/<ResourceType>,<new_property>")

Example:

new_resource={
   "@type" : "Movie",
   "movie_name" : "The Shining",
   "movie_director" : "Stanley Kubrick"
}
agent.put("http://localhost:8080/serverapi/Movie/", new_resource)

Example output:

({'@context': 'http://www.w3.org/ns/hydra/context.jsonld', '@type': 'Status', 'description': 'Object with ID 9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed successfully added', 'statusCode': 201, 'title': 'Object successfully added'}, 'http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed')
  1. To add new members to a collection:

Syntax:

request_body = {
   "@type": "<CollectionType>",
   "members": [
      {
            "@id": "<ResourceID>",
            "@type": "<ResourceType>"
      },
      {
            "@id": "<ResourceID>",
            "@type": "<ResourceType>"
      },
   ]
}
agent.put("http://localhost:8080/serverapi/<CollectionType>", request_body)

Example:

request_body = {"@type" : "MovieCollection","members": [{"@id" : "9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed","@type" : "Movie"},]}
agent.put("http://localhost:8080/serverapi/MovieCollection", request_body)

Example output:

({'@context': 'http://www.w3.org/ns/hydra/context.jsonld', '@type': 'Status', 'description': 'Object with ID 2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3 successfully added', 'statusCode': 201, 'title': 'Object successfully added'}, 'http://localhost:8080/serverapi/MovieCollection/2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3')
  1. To GET a resource:
  1. To get a collection, the syntax is
agent.get("http://localhost:8080/serverapi/<CollectionType>/")

Example:

agent.get("http://localhost:8080/serverapi/MovieCollection")
Output:
Returns the ApiDoc for the resource MovieCollection
  1. To get members of a specific collection, the syntax is
agent.get("http://localhost:8080/serverapi/<CollectionType>/<Collection-ID>")

Example:

agent.get("http://localhost:8080/serverapi/MovieCollection/2d2bdaa9-8f9c-46fe-ac16-6d69b7e52bf3")
  1. To get members of a specific resource, the syntax is
agent.get("http://localhost:8080/serverapi/<ResourceType>/<Resource-ID>")

Example:

agent.get("http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed")

Example output:

{'@context': '/serverapi/contexts/Movie.jsonld', '@id': '/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed', '@type': 'Movie', 'movie_director': 'Stanley Kubrick', 'movie_name': 'The Shining'}

Note: Collection-IDs and Resource-IDs are present in the database file generated after running hydrus.

  1. To update a resource using a POST request:

Syntax:

agent.post("http://localhost:8080/serverapi/<ResourceType>/<Resource-ID>,<updated_property>")

Example:

existing_resource["movie_name"] = "A Clockwork Orange"
agent.post("http://localhost:8080/serverapi/Movie/9b1a5cb1-aaa3-411c-a4a6-93d0c4446fed", existing_resource)
.. toctree::
   :maxdepth: 2
   :caption: Contents:

   agent
   collection_paginator
   helpers
   querying_mechanism

Indices and tables