vovk generate

TODO: Flags here

The command vovk generate generates client at node_modules/.vovk-client folder from the schema at .vovk-schema folder that in its turn was generated by Vovk Dev Watcher that is run by vovk dev command.


npx vovk generate
# or
npx vovk g

Its automatically added to the "generate" script in the package.json file when vovk init is run.


{
  "scripts": {
    // ...
    "generate": "vovk generate"
  }
}

You can specify the output directory with --out (shortcut for --client-out-dir) flag and prettify the output with --prettify flag.


npx vovk generate --out ./client --prettify

Vercel build

In order to build the client at Vercel, you need to add "vercel-build" script to the package.json with generate script.


{
  "scripts": {
    // ...
    "build": "next build",
    "generate": "vovk generate",
    "vercel-build": "npm run build && npm run generate"
  }
}

Custom templates (experimental)

Vovk.ts offers a way to generate a completely custom client library, including a client for a different programming language using EJS templates or just copying over any non-EJS files.

You can achieve this by specifying templates with --template (or --templates) flag with either path to a template file or one of the predefined values: ts, compiled, python, none. The none value is used to skip the client generation. It’s useful when you want to generate only the schema with --full-schema flag described below.


npx vovk generate --template ./path/to/template.js.ejs --template ./path/to/another-template.py.ejs --template ts

If --template receives a path to a file, it should be an EJS template with .ejs extension or any other file that’s going to be copied over to the output directory.

Please check the default templates to see how to create your own.

By the time being, there is the available variables passed to a EJS template:


const ejsData = {
  apiRoot, // API root made from config.origin and config.rootEntry
  fetcherClientImportPath, // Import path to the default fetcher or custom fetcher defined as config.fetcher
  schemaOutImportPath, // Import path to the schema output directory
  validateOnClientImportPath, // Import path to the validateOnClient file
  segments, // List of segments, an array of { routeFilePath: string; segmentName: string; segmentImportPath: string; }
  segmentsSchema, // Collection of schema: Record<string, import('vovk').VovkSchema>
};

—full-schema flag

The --full-schema flag generates a single .json file that combines all the schema objects into one.


npx vovk generate --full-schema

By default the file is named full-schema.json but you can specify a custom name with the flag.


npx vovk generate --full-schema=my-schema.json

To skip the client generation and generate only the full schema, use the --template none flag.


npx vovk generate --full-schema --template none

The signature of the full schema file is Record<string, import('vovk').VovkSchema>, where the key is the segment name and the value is the schema object for that segment.

You can also specify experimental_clientGenerateTemplateNames at config to provide a list of templates that are going to be used by vovk generate command. By default it’s value is ['ts', 'compiled'] but you can redefine it to generate the client from the other templates or provide less items, like ['ts'] to generate only an uncompiled TypeScript file.


const config = {
  // ...
  experimental_clientGenerateTemplateNames: [
    'ts',
    'compiled',
    'python',
    './my-client-templates/custom-template.js.ejs',
  ],
};

Python client (experimental)

Vovk.ts offers a way to generate a Python client library using a custom EJS template. You can achieve this by specifying python value with --template flag. It reads the schema from the full-schema.json to build a library with similar functionality to the TypeScript client.


npx vovk generate --template python --full-schema --out ./client

The command copies over **init.py** file, located at vovk-cli/client-templates/python .

The Python client is experimental and created as a proof of concept. It’s going to be improved in the future to provide better typing and nicer developer experience. Feel free to contribute.


from client import UserRPC, LanguageModelRPC, ServerError
from jsonschema.exceptions import ValidationError
import requests
 
if __name__ == "__main__":
    base_url = "http://localhost:3000/api"
 
    try:
        # 1) Non-streaming usage: returns a dict (parsed JSON) or text, etc.
        resp_data = UserRPC.postWithBodyQueryAndParams(
            base_url,
            query={'hey': 'query'},
            body={'hello': 'body'},
            params={'foo': 'bar'}
        )
        # resp_data will be either JSON (Python dict) or text, depending on the content type
        print("Non-streaming response:", resp_data)
 
        # 2) Streaming usage: if endpoint returns 'x-vovk-stream: true'
        #    we'll get a generator
        stream_data = LanguageModelRPC.getWithStreaming(
            base_url,
            query={'query': 'streamme'},
            body=None,
            params=None
        )
 
        # Check if it's a generator
        if hasattr(stream_data, '__iter__'):
            print("\nStreaming data:")
            for item in stream_data:
                print("Got item:", item)
        else:
            # It's not streaming, so it's just the final data
            print("\nGot a non-stream response for streaming endpoint:", stream_data)
 
    except ServerError as se:
        print("ServerError caught:", se)
        print("Status code:", se.status_code)
        print("Message:", se.server_message)
 
    except ValidationError as ve:
        print("Client-side validation error:", ve.message)
 
    except requests.HTTPError as he:
        print("HTTP error:", he)