{"id":22741795,"url":"https://github.com/http-apis/hydra-python-agent","last_synced_at":"2025-08-09T14:27:26.943Z","repository":{"id":29501083,"uuid":"121865072","full_name":"HTTP-APIs/hydra-python-agent","owner":"HTTP-APIs","description":"Python Hydra smart client and test console","archived":false,"fork":false,"pushed_at":"2023-05-23T02:04:11.000Z","size":664,"stargazers_count":22,"open_issues_count":23,"forks_count":42,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2025-04-11T23:22:31.966Z","etag":null,"topics":["client","graph","python","rest-api"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/HTTP-APIs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-02-17T15:13:46.000Z","updated_at":"2022-06-16T04:43:36.000Z","dependencies_parsed_at":"2024-04-12T08:23:12.871Z","dependency_job_id":"eb56eb01-f29a-40a1-90de-917fa61c05a9","html_url":"https://github.com/HTTP-APIs/hydra-python-agent","commit_stats":{"total_commits":264,"total_committers":19,"mean_commits":"13.894736842105264","dds":0.5681818181818181,"last_synced_commit":"353e43e9d8e4778f457b086801fe127e798af464"},"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HTTP-APIs%2Fhydra-python-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HTTP-APIs%2Fhydra-python-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HTTP-APIs%2Fhydra-python-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/HTTP-APIs%2Fhydra-python-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/HTTP-APIs","download_url":"https://codeload.github.com/HTTP-APIs/hydra-python-agent/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248837429,"owners_count":21169432,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["client","graph","python","rest-api"],"created_at":"2024-12-11T00:17:49.450Z","updated_at":"2025-04-14T07:22:41.205Z","avatar_url":"https://github.com/HTTP-APIs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hydra-python-agent [![Build Status](https://travis-ci.com/HTTP-APIs/hydra-python-agent.svg?branch=master)](https://travis-ci.com/HTTP-APIs/hydra-python-agent)\n\nFor a general introduction to Hydra Ecosystem, see [hydraecosystem.org](http://hydraecosystem.org).\n\n`hydra-python-agent` is a smart Hydra client implemented in Python which works with [hydrus](https://github.com/HTTP-APIs/hydrus). Reference implementation is [Heracles.ts](https://github.com/HydraCG/Heracles.ts). Smart clients are generic automated clients that establish resilient connected data networks leveraging knowledge graphs.\n\n## Quick Start\nOur Hydra Agent has different interfaces that you can try:\n\n- [A Web-based GUI](https://github.com/HTTP-APIs/hydra-python-agent-gui/tree/agent-gui-1.0/console-frontend) - which shows how Hydra APIs are connected and how the Smart Agent is generic and can automatically build requests.  \n- [A Python package](https://github.com/HTTP-APIs/hydra-python-agent/#user-content-agent-package) - so you can use to communicate with a Hydra API in your code/software. \n- [Natural-language-like command line tool](#natural-language-like-command-line-tool) - this is still a GET only implementation\n\n## General characteristics\n\nThe Agent is *designed* to:\n* Provide a seamless Client that can be used to communicate with Hydra APIs\n* Cache metadata from the Hydra server it connects to, to allow querying on the client-side\n* Maintain a syncrhonization mechanism which makes sure cached resources are consistent\n* The graph can be queried using OpenCypher.\n\nThe 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.\n\n## Installation\n\n**NOTE:** You'll need to use python3. Using venv(virtual environment) is recommended.\n\nClone and setup a virtual environment:\n   \n    git clone https://github.com/HTTP-APIs/hydra-python-agent.git\n    cd hydra-python-agent\n    python3 -m venv venv\n    source venv/bin/activate\n\nInstall dependencies and setup Agent:\n\n    pip3 install --upgrade pip\n    pip3 install -r requirements.txt\n    python3 setup.py install\n\nSetup Redis which is used as caching layer(if permission denied use `sudo`):\n\n    ./redis_setup.sh\n\n**Setup hydrus**\nSince this is an API Client, we need an appropriate Hydra Server to query to. To setup a localhost follow the instructions at https://github.com/HTTP-APIs/hydrus#demo. You might want to run `hydrus serve --no-auth` to skip setting up headers.\n\n#### Agent package \nAfter installing the Agent and running Redis, [as per instructions above](https://github.com/HTTP-APIs/hydra-python-agent/#user-content-installation), you can do something like:\n\n```\nfrom hydra_agent.agent import Agent \n\nagent = Agent(\"http://localhost:8080/serverapi/\") # \u003c- hydrus Server URL \nagent.get(\"http://localhost:8080/serverapi/DroneCollection/\")\n```\n\nThe agent supports GET, PUT, POST or DELETE:\n\n- **GET** - used to READ resources or collections\n- **PUT** - used to CREATE new resources in the Server\n- **POST** - used to UPDATE resources in the Server\n- **DELETE** - used to DELETE resources in the Server\n\n**To GET** a existing resource you should:\n```\nagent.get(\"http://localhost:8080/serverapi/\u003cResourceType\u003e/\u003cResource-ID\u003e\")\nagent.get(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e/\")\nagent.get(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e/\u003cCollection-ID\u003e\")\n```\n\n**To PUT** a new resource say on a Drone endpoint, you should:\n```\nnew_resource = {\n    \"@type\": \"Drone\",\n    \"DroneState\": {\n        \"@type\": \"State\",\n        \"Battery\": \"50%\",\n        \"Direction\": \"N\",\n        \"Position\": \"50.34\",\n        \"SensorStatus\": \"Active\",\n        \"Speed\": \"100\"\n    },\n    \"MaxSpeed\": \"500\",\n    \"Sensor\": \"Active\",\n    \"model\": \"Drone_1\",\n    \"name\": \"Drone1\"\n}\nagent.put(\"http://localhost:8080/serverapi/Drone/\", new_resource)\n```\n\n**To UPDATE** a resource you should:\n```\nexisting_resource[\"name\"] = \"Updated Name\"\nagent.post(\"http://localhost:8080/serverapi/\u003cResourceType\u003e/\u003cResource-ID\u003e\", existing_resource)\n```\n\n**To DELETE** a resource you should:\n```\nagent.delete(\"http://localhost:8080/serverapi/\u003cResourceType\u003e/\u003cResource-ID\u003e\")\n```\n**To ADD** members in collection:\n```\nrequest_body = {\n    \"@type\": \"\u003cCollectionType\u003e\",\n    \"members\": [\n        {\n            \"@id\": \"\u003cResourceID\u003e\",\n            \"@type\": \"\u003cResourceType\u003e\"\n        },\n        {\n            \"@id\": \"\u003cResourceID\u003e\",\n            \"@type\": \"\u003cResourceType\u003e\"\n        },\n    ]\n}\nagent.put(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e\", request_body)\n```\nNOTE: \\\u003cResourceType\\\u003e can be different in given request body. \n\n**TO GET** members of specific Collection:\n```\nagent.get(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e/\u003cCollectionID\u003e\")\n```\n**TO UPDATE** members of specific collection:\n```\nupdated_collection = {\n    \"@type\": \"\u003cCollectionType\u003e\",\n    \"members\": [\n        {\n            \"@id\": \"\u003cResourceID\u003e\",\n            \"@type\": \"\u003cResourceType\u003e\"\n        },\n        {\n            \"@id\": \"\u003cResourceID\u003e\",\n            \"@type\": \"\u003cResourceType\u003e\"\n        },\n    ]\n}\nagent.post(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e/\u003cCollectionID\u003e\",updated_collection )\n```\n**TO DELETE** members of specific Collection:\n```\nagent.delete(\"http://localhost:8080/serverapi/\u003cCollectionType\u003e/\u003cCollectionID\u003e\")\n```\nMore than that, Agent 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.\n\n### Natural-language-like Command Line Tool\nIf you've followed the [installation](#installation) instructions you can run: \n\n    python hydra_agent/querying_mechanism.py\n\nAnother alternative to run the CLT is using docker componse. To run **both Redis server and the client**(stop any Redis instance before), you can run the command:\n    \n        docker-compose run client\n\nTo query you should provide a hydrus URL first:\n\n```\n     url\u003e\u003e\u003e http://localhost:8080/serverapi/ \n   \n```\n\n**Obs.: If failing to connect to localhost** running the Agent via Docker, head to [issue #104](https://github.com/HTTP-APIs/hydra-python-agent/issues/104#issuecomment-497381440).\n\n- **Natural Language querying format**\n\nRun help inside the CLT to get the querying format.\n\n        \u003e\u003e\u003ehelp # it will provide the querying format\n\nYou can query the server with the following format:\n\n\n\u003e Get all endpoints:- **show endpoints**\nGet all class_endpoints:- **show classEndpoints**\nGet all collection_endpoints:- **show collectionEndpoints**\nGet all members of collection_endpoint:- **show \u003c collection_endpoint \u003e members**\nGet all properties of objects:- **show objects\u003c endpoint_type \u003e properties**\nGet all properties of any member:- **show object\u003c id_of_member \u003e properties **\nGet all classes properties:- **show class\u003c class_endpoint \u003e properties**\nGet data with compare properties:- **show \u003c key \u003e \u003c value \u003e and/or \u003c key1 \u003e \u003c value1 \u003e**\nGet data by using both opeartions(and,or)  you should use brackets like:- **show model xyz and (name Drone1 or name Drone2) or, show \u003c key \u003e \u003c value \u003e and (\u003c key \u003e \u003c value \u003e or \u003c key \u003e \u003c value \u003e)**\n\nFor more detail take a look at [wiki file](https://github.com/HTTP-APIs/http-apis.github.io/blob/master/hydra-agent-redis-graph.md)\n\n### Missing bits at the moment\n* For the Web GUI there's a list of [future enhacements here](https://github.com/HTTP-APIs/hydra-python-agent-gui/issues/3).\n* For now the Natural language CLT it is a proof-of-concept, only `GET` functionality\n\nReferences\n----------\n\n[Hydra-Enabled smart client](http://www.hydra-cg.com/)\n\n[Hydra core vocabulary](http://www.hydra-cg.com/spec/latest/core/)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttp-apis%2Fhydra-python-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhttp-apis%2Fhydra-python-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhttp-apis%2Fhydra-python-agent/lists"}