{"id":18565230,"url":"https://github.com/rigetti/rpcq","last_synced_at":"2025-12-12T00:50:59.939Z","repository":{"id":33181120,"uuid":"152646040","full_name":"rigetti/rpcq","owner":"rigetti","description":"The RPC framework and message specification for @rigetti Quantum Cloud Services.","archived":false,"fork":false,"pushed_at":"2023-05-30T07:17:26.000Z","size":370,"stargazers_count":78,"open_issues_count":23,"forks_count":29,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-03-18T07:09:32.995Z","etag":null,"topics":["lisp","python","qcs","quantum-computing","rpc"],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rigetti.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-11T19:38:34.000Z","updated_at":"2025-03-17T19:23:17.000Z","dependencies_parsed_at":"2024-06-18T18:37:08.182Z","dependency_job_id":null,"html_url":"https://github.com/rigetti/rpcq","commit_stats":null,"previous_names":["rigetticomputing/rpcq"],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Frpcq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Frpcq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Frpcq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rigetti%2Frpcq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rigetti","download_url":"https://codeload.github.com/rigetti/rpcq/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248157619,"owners_count":21057042,"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":["lisp","python","qcs","quantum-computing","rpc"],"created_at":"2024-11-06T22:17:59.801Z","updated_at":"2025-12-12T00:50:59.902Z","avatar_url":"https://github.com/rigetti.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"rpcq\n====\n\n[![pypi version](https://img.shields.io/pypi/v/rpcq.svg)](https://pypi.org/project/rpcq/)\n[![conda-forge version](https://img.shields.io/conda/vn/conda-forge/rpcq.svg)](https://anaconda.org/conda-forge/rpcq)\n[![docker pulls](https://img.shields.io/docker/pulls/rigetti/rpcq.svg)](https://hub.docker.com/r/rigetti/rpcq)\n\nThe asynchronous RPC client-server framework and message specification for\n[Rigetti Quantum Cloud Services (QCS)](https://www.rigetti.com/).\n\nImplements an efficient transport protocol by using [ZeroMQ](http://zeromq.org/) (ZMQ) sockets and\n[MessagePack](https://msgpack.org/index.html) (`msgpack`) serialization.\n\nNot intended to be a full-featured replacement for other frameworks like\n[gRPC](https://grpc.io/) or [Apache Thrift](https://thrift.apache.org/).\n\nPython Installation\n-------------------\n\nTo install directly from the source, run `pip install -e .` from within the top-level\ndirectory of the `rpcq` repository. To additionally install the requirements for testing,\nmake sure to run `pip install -r requirements.txt`.\n\nTo instead install the latest released verson of `rpcq` from the Python package manager PyPi,\nrun `pip install rpcq`.\n\n**NOTE**: We strongly encourage users of `rpcq` to install the software within a (Python)\nvirtual environment (read up on [`virtualenv`](https://github.com/pypa/virtualenv),\n[`pyenv`](https://github.com/pyenv/pyenv), or [`conda`](https://github.com/conda/conda)\nfor more info).\n\nLisp Installation\n-----------------\n\nInstallation is easier with QuickLisp. After placing the source for RPCQ within your local\nLisp projects directory (cf. `ql:*local-project-directories*`), run `(ql:quickload :rpcq)`\nand QuickLisp will download the necessary Lisp dependencies.\n\nIn addition to the Lisp dependencies, RPCQ depends on ZeroMQ.  Be sure to install both the\nlibrary *and* its development headers (which are necessary for the Lisp foreign-function\ninterface to get its bearings).\n\nUsing the Client-Server Framework\n---------------------------------\n\nThe following two code samples (first in Python, then in Lisp) demonstrate how to create a server, add a test handler, and spin it up.\n\n```python\nfrom rpcq import Server\n\nserver = Server()\n\n@server.rpc_handler\ndef test():\n    return 'test'\n\nserver.run('tcp://*:5555')\n```\n\n```lisp\n(defun test ()\n  \"test\")\n\n(let ((dt (rpcq:make-dispatch-table)))\n  (rpcq:dispatch-table-add-handler dt 'test)\n  (rpcq:start-server :dispatch-table dt\n                     :listen-addresses '(\"tcp://*:5555\")))\n```\n\nIn another window, we can (again first in Python, then in Lisp) create a client that points to the same socket, and call the test method.\n\n```python\nfrom rpcq import Client\n\nclient = Client('tcp://localhost:5555')\n\nclient.call('test')\n```\n\n```lisp\n(rpcq:with-rpc-client (client \"tcp://localhost:5555\")\n  (rpcq:rpc-call client \"test\"))\n```\n\nIn all cases (including interoperating a client/server pair written in different languages), this will return the string `'test'`.\n\nUsing the Message Spec\n----------------------\n\nThe message spec as defined in `src/messages.lisp` (which in turn produces `rpcq/messages.py`)\nis meant to be used with the [Rigetti QCS](https://www.rigetti.com/qcs) platform. Therefore,\nthese messages are used in [`pyquil`](https://github.com/rigetticomputing/pyquil), in order\nto allow users to communicate with the Rigetti Quil compiler and quantum processing units (QPUs).\nPyQuil provides utilities for users to interact with the QCS API and write programs in\n[Quil](https://arxiv.org/abs/1608.03355), the quantum instruction language developed at Rigetti.\n\nThus, most users will not interact with `rpcq.messages` directly. However, for those interested\nin building their own implementation of the QCS API utilities in pyQuil, becoming acquainted\nwith the client-server framework, the available messages in the message spec, and how they\nare used in the `pyquil.api` module would be a good place to start!\n\nUpdating the Python Message Bindings\n------------------------------------\n\nCurrently only Python bindings are available for the message spec, but more language bindings\nare in the works. To update the Python message bindings after editing `src/messages.lisp`,\nopen `rlwrap sbcl` and run:\n\n```lisp\n(ql:quickload :rpcq)\n(with-open-file (f \"rpcq/messages.py\" :direction :output :if-exists :supersede)\n  (rpcq:python-message-spec f))\n```\n\n**NOTE**: Requires pre-installed\n[`sbcl`](http://www.sbcl.org/),\n[`quicklisp`](https://www.quicklisp.org/beta/), and\n(optionally) [`rlwrap`](https://github.com/hanslub42/rlwrap).\n\nWe can also use the rpcq docker container to update the message spec without to install the\nrequirements.\n\n```bash\n./docker_update_python_spec.sh\n```\n\nRunning the Unit Tests\n----------------------\n\nThe `rpcq` repository is configured with GitLab CI to automatically run the unit tests.\nThe tests run within a container based off of the\n[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific\ntag. If you need a more recent version of the image, update the tag in the `.gitlab-ci.yml`.\n\nThe Python unit tests can be executed locally by running `pytest` from the top-level\ndirectory of the repository (assuming you have installed the test requirements).\n\nThe Lisp unit tests can be run locally by doing the following from within `rlwrap sbcl`:\n\n```lisp\n(ql:quickload :rpcq)\n(asdf:test-system :rpcq)\n```\n\nThere may be some instances of `STYLE-WARNING`, but if the test run successfully,\nthere should be something near the bottom of the output that looks like:\n\n```\nRPCQ-TESTS (Suite)\n  TEST-DEFMESSAGE                                                         [ OK ]\n```\n\nAutomated Packaging with Docker\n-------------------------------\n\nThe CI pipeline for `rpcq` produces a Docker image, available at\n[`rigetti/rpcq`](https://hub.docker.com/r/rigetti/rpcq). To get the latest stable\nversion of `rpcq`, run `docker pull rigetti/rpcq`. The image is built from the\n[`rigetti/lisp`](https://hub.docker.com/r/rigetti/lisp) Docker image, which is pinned to a specific\ntag. If you need a more recent version of the image, update the tag in the `Dockerfile`.\n\nTo learn more about the `rigetti/lisp` Docker image, check out the\n[`docker-lisp`](https://github.com/rigetti/docker-lisp) repository.\n\nRelease Process\n---------------\n\n1. Update `VERSION.txt` and dependency versions (if applicable) and push the commit to `master`.\n2. Push a git tag `vX.Y.Z` that contains the same version number as in `VERSION.txt`.\n3. Verify that the resulting build (triggered by pushing the tag) completes successfully.\n4. Push the tagged commit to `pypi` and verify it appears [here](https://pypi.org/project/rpcq/).\n5. Publish a [release](https://github.com/rigetti/rpcq/releases) using the tag as the name.\n6. Close the [milestone](https://github.com/rigetti/rpcq/milestones) associated with this release,\n   and migrate incomplete issues to the next one.\n\nAuthors\n-------\n\nDeveloped at [Rigetti Computing](https://github.com/rigetticomputing) by\n[Nikolas Tezak](https://github.com/ntezak),\n[Steven Heidel](https://github.com/stevenheidel),\n[Eric Peterson](https://github.com/ecp-rigetti),\n[Colm Ryan](https://github.com/caryan),\n[Peter Karalekas](https://github.com/karalekas),\n[Guen Prawiroatmodjo](https://github.com/guenp),\n[Erik Davis](https://github.com/kilimanjaro), and\n[Robert Smith](https://github.com/tarballs-are-good).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigetti%2Frpcq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frigetti%2Frpcq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frigetti%2Frpcq/lists"}