diff --git a/docs/doczrc.js b/docs/doczrc.js index f0b27e4..b72cf47 100644 --- a/docs/doczrc.js +++ b/docs/doczrc.js @@ -3,7 +3,7 @@ export default { menu:[ "Welcome to Hydra Ecosystem Docs", "Quickstart", - {name: 'Tutorial', menu:['First Tutorial']}, + {name: 'Tutorial', menu:['Using agent to query hydrus']}, {name: 'How To Guides', menu: ['First How to Guide']}, {name: 'Conceptual Guides', menu: ['Conceptual Guide 1']}, {name: 'Modules', menu: ['Hydra in Depth']}, diff --git a/docs/src/content/tutorial/first.md b/docs/src/content/tutorial/first.md deleted file mode 100644 index 8a1d209..0000000 --- a/docs/src/content/tutorial/first.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -name: First Tutorial -menu: Tutorial ---- - -# First Tutorial - -## How to say hello in Python? - -```python - import __hello__ - def hello(): - print("Hello there, again") - -``` - -## How to say hello in Python Again? - -```python - import __hello__ - def hello(): - print("Hello there, again") - -``` diff --git a/docs/src/content/tutorial/using-agent-to-query.md b/docs/src/content/tutorial/using-agent-to-query.md new file mode 100644 index 0000000..91a6bba --- /dev/null +++ b/docs/src/content/tutorial/using-agent-to-query.md @@ -0,0 +1,137 @@ +--- +name: Using agent to query hydrus +menu: Tutorial +--- + +# Using Agent to query Hydrus + +> You should have `hydrus` up and running. For instructions on how to start a hydrus server, checkout the quick start guide. To follow along you also need to have `git` and `python3` installed. + +`hydra-python-agent` or Agent is the smart Hydra client implemented in Python. The Agent is a smart client which is generic and automated that can establish resilient connected data networks leveraging knowledge graph. + +`hydra-python-agent` exposes multiple convenient interfaces: + +- A Python package - To make communication with a Hydra API easier in the software. +- Natural-language-like command line tool - This is a GET only implementation for now. It is in development. + + +Some of the important features of `hydra-python-agent` are: + +1. It provides a seamless client that can be used to communicate with Hydra APIs. +2. It caches metadata from the Hydra server it connects to, to allow querying on the client-side. +3. It maintains a synchronization mechanism which makes sure cached resources are consistent. +4. It allows the graph to be queried using OpenCypher. + +## To use agent as a package in REPL: + +1. Clone the repository by running this command in the terminal: `git clone https://github.com/HTTP-APIs/hydra-python-agent.git`. +2. Navigate into the repository by running: `cd hydra-python-agent` +3. Create a new virtual environment named agent: `python3 -m venv agent`. +4. Activate this virtual environment: `source agent/bin/activate`. +5. Install the necessary package: `pip install -r requirements.txt`. After this run: `python3 setup.py install`. +6. Start the redis server: `docker run -p 6379:6379 -it --rm redislabs/redisgraph:2.0-edge`. The agent uses redis to cache the meta data to make query faster. +7. Start the python3 REPL by typing `python3` and pressing enter. You should see something like this: + ![REPL](../../../static/images/repl.png) +8. In the REPL, import Agent: + +```python +from hydra_agent.agent import Agent +``` + +9. Connect Agent to hydrus by passing in the URL. The `Agent` is the factory class that returns the instance of the agent. All the CRUD operations can be invoked on this instance. + +```python +agent = Agent("http://localhost:8080/serverapi") # serverapi is the name of the API. +``` + +10. Once connected, we can now make CRUD operations. + +## Making CRUD Operations on Classes + +To GET an existing resource make a GET request to: + +```python +agent.get("http://localhost:8080/serverapi//") +agent.get("http://localhost:8080/serverapi//") +agent.get("http://localhost:8080/serverapi//") +``` + +You should see the response. + +To add a resource make a PUT request with the resource as the second parameter: + +```python +new_resource = { + "@type": "Drone", + "DroneState": { + "@type": "State", + "Battery": "50%", + "Direction": "N", + "Position": "50.34", + "SensorStatus": "Active", + "Speed": "100" + }, + "MaxSpeed": "500", + "Sensor": "Active", + "model": "Drone_1", + "name": "Drone1" +} +agent.put("http://localhost:8080/serverapi/Drone/", new_resource) +``` + +To update the resource Agent exposes the POST interface: + +```python +existing_resource["name"] = "Updated Name" +agent.post("http://localhost:8080/serverapi//", existing_resource) +``` + +To delete an existing resource, use the delete method: + +```python +agent.delete("http://localhost:8080/serverapi//") +``` + +## Making CRUD Operations on Collections + +To add members in the collection: + +``` +request_body = { + "@type": "", + "members": [ + { + "@id": "", + "@type": "" + }, + { + "@id": "", + "@type": "" + }, + ] +} +agent.put("http://localhost:8080/serverapi/", request_body) +``` + +NOTE: \ can be different in given request body. + +TO GET members of specific Collection: + +```python +agent.get("http://localhost:8080/serverapi//") +``` + +TO DELETE members of specific Collection: + +```python +agent.delete("http://localhost:8080/serverapi//") +``` + +More than that, `Agent` class extends Session from https://2.python-requests.org/en/master/api/#request-sessions, so all methods like auth, cookies, headers and so on can also be used. + +### In this Tutorial you learnt about: + +- smart clients +- `hydra-python-agent` +- Making CRUD operations using `hydra-python-agent` on classes +- Making CRUD operations using `hydra-python-agent` on Collections diff --git a/docs/static/images/repl.png b/docs/static/images/repl.png new file mode 100644 index 0000000..a5fd9e7 Binary files /dev/null and b/docs/static/images/repl.png differ