gRPC API
========

All Jarvis AI Services described in this document are exposed using
`gRPC <https://grpc.io/>`_ to maximize compatibility with existing
software infrastructure and ease integration. gRPC officially supports
`twelve languages <https://grpc.io/docs/>`_, including C++, Java,
Python, and Golang, with unofficial support for many others.

The gRPC services and messages/data structures are defined with protocol
buffer definition files, which are packaged with this release. Using
these files, you can generate Jarvis AI Services bindings to any
supported language of your choice. The generated code can be compiled
into your application, with the only additional dependency being the
gRPC library.


Generating Bindings
-------------------

The process for generating bindings is dependent on the target language you
intend to use for developing with Jarvis. The high-level steps, however,
are the same.

#.  Download, build (if necessary) and install gRPC for your target platform
    and language.

#.  Obtain the gRPC service and protocol buffer definitions for Jarvis from NGC:

    .. prompt:: bash
       :substitutions:

       ngc registry resource download-version |NgcOrgTeam|/jarvis_quickstart:|VersionNum|
       cd jarvis_quickstart_v|VersionNum|/protos

#.  Generate language-specific bindings using the ``protoc`` tool (see `gRPC docs <https://grpc.io/docs/>`_).

#.  Write a client in your desired language with the generated bindings in the previous step.


Tutorial
--------

In this tutorial, we will build a question answering application with Jarvis written in 
`Golang <https://golang.org/>`_.

#.  `Download and install Golang <https://golang.org/dl/>`_ compiler if you have not already.
    Ensure that ``$GOPATH/bin`` is in your environment ``$PATH`` so that you can use 
    Golang-installed tools (like protoc).

#.  Install the Protocol Buffers and gRPC libraries for Golang.

    .. prompt:: bash
        :substitutions: 

        export GO111MODULE=on
        go get -u google.golang.org/protobuf/cmd/protoc-gen-go
        go get -u google.golang.org/grpc/cmd/protoc-gen-go-grpc

#.  Create a directory for our project. Initialize a module with ``go mod``.

    .. prompt:: bash
        :substitutions:

        mkdir jarvis-qa-golang-client
        cd jarvis-qa-golang-client
        go mod init jarvis-qa

#.  Download and copy the Jarvis API definition from NGC.

    .. prompt:: bash
        :substitutions:

        ngc registry resource download-version |NgcOrgTeam|/jarvis_quickstart:|VersionNum|
        cp -R jarvis_quickstart_v|VersionNum|/protos jarvis_speech
        rm -rf jarvis_quickstart_v|VersionNum|

#.  Generate Golang bindings for the Jarvis NLP service.

    .. prompt:: bash
        :substitutions:

        cd jarvis_speech
        protoc --go_out=. --go_opt=paths=source_relative \
               --go-grpc_out=. --go-grpc_opt=paths=source_relative \
               jarvis_nlp.proto jarvis_core_nlp.proto
        cd ..

#.  Write a simple synchronous client. Using the text editor or IDE of your choice, create a
    source file for our executable ``qa.go`` with the following code.

    .. code-block:: go
        :linenos:

        package main

        import (
            "context"
            "flag"
            "log"
            "time"

            "google.golang.org/grpc"
            pb "jarvis-qa/jarvis_speech"
        )

        func main() {
            serverFlag := flag.String("server", "localhost:50051", "Jarvis server to connect to")
            queryFlag := flag.String("query", "", "Question to ask")
            contextFlag := flag.String("context", "", "Context to search for answer")

            flag.Parse()

            if *queryFlag == "" || *contextFlag == "" {
                log.Fatal("-query and -context must both be set.")
            }

            // Set up a connection to the server.
            conn, err := grpc.Dial(*serverFlag, grpc.WithInsecure(), grpc.WithBlock(), grpc.WithTimeout(time.Second))
            if err != nil {
                log.Fatalf("Unable to connect to server: %v", err)
            }
            defer conn.Close()
            c := pb.NewJarvisNLPClient(conn)

            // Contact the server and print out its response.
            ctx, cancel := context.WithTimeout(context.Background(), time.Second)
            defer cancel()

            r, err := c.NaturalQuery(ctx, &pb.NaturalQueryRequest{
                Query:   *queryFlag,
                Context: *contextFlag,
                TopN:    1,
            })

            if err != nil {
                log.Fatalf("Issue encountered with Jarvis Request: %v", err)
            }

            log.Printf("Question: %s", *queryFlag)
            log.Printf("Answer:   %s", r.GetResults()[0].GetAnswer())
        }

#. Compile and run the new client.
    
    .. code-block:: bash
        :substitutions:

        $ go build qa.go
        $ ./qa -server <jarvis_uri> \
             -query "Which founder of NVIDIA previously worked at Sun?" \
             -context "Nvidia was founded on April 5, 1993, by Jensen Huang (CEO as of 
                  2020), a Taiwanese American, previously director of CoreWare at LSI 
                  Logic and a microprocessor designer at Advanced Micro Devices (AMD), 
                  Chris Malachowsky, an electrical engineer who worked at Sun 
                  Microsystems, and Curtis Priem, previously a senior staff engineer 
                  and graphics chip designer at Sun Microsystems."

        2021/02/04 13:17:51 Question: Which founder of NVIDIA previously worked at Sun?
        2021/02/04 13:17:51 Answer:   Chris Malachowsky,