Smarter CLI

The Smarter cli is a standalone application written in Go lang that runs on Windows, macOS and Linux. It is separately managed in github.com/smarter-sh/smarter-cli. It is a lightweight command-line UI for interacting with the Smarter API.

Installation

See https://smarter.sh/cli for download instructions for Windows, macOS and Linux.

Usage

Works like kubectl, the Smarter cli uses a verb-noun command structure to interact with Smarter resources. The general format is:

smarter [command] [flags]

Available Commands:
  apply       Apply a Smarter manifest
  chat        Chat with a deployed LLMClient
  completion  Generate the autocompletion script for the specified shell
  configure   Configure the smarter command-line interface
  delete      Permanently delete a Smarter resource
  deploy      Deploy a resource
  describe    Return a manifest for the resource kind
  get         Generate a list of Smarter resources
  help        Help about any command
  logs        Returns the logs for a resource
  manifest    Generate an example manifest for the resource kind
  status      Retrieve real-time status of the Smarter Platform
  undeploy    Undo a Smarter resource deployment.
  version     Retrieve version information
  whoami      Retrieve information about the api_key owner

Flags:
      --api_key string         Smarter API key to use
      --config string          config file (default is $HOME/.smarter/config.yaml)
      --environment string     environment to use: local, alpha, beta, next, prod. Default is prod
  -h, --help                   help for smarter
  -o, --output_format string   output format: json, yaml (default "json")
  -v, --verbose                verbose output

Commands

The cli implements a set of verbs for working with Smarter resources

• apply: executes services as necessary in order to migrate a Smarter resource from its present state to that which is described in the provided manifest.

• delete: permanently, unrecoverably destroys a Smarter resource.

• deploy: manages the deploy state of a deployable Smarter resource (Plugin and LLMClient).

• describe: returns a report in yaml or json format that is a superset of a manifest describing the present state of a Smarter resource.

• logs: returns log data in standard console log format for a Smarter resource

• status: returns a report in yaml or json format that provides real-time information on the state of the Smarter platform.

Related API endpoints

• https://api.example.com/v1/cli/apply/: Apply a manifest

• https://api.example.com/v1/cli/describe/: print the manifest

• https://api.example.com/v1/cli/deploy/: Deploy a resource

• https://api.example.com/v1/cli/logs/: Get logs for a resource

• https://api.example.com/v1/cli/delete/: Delete a resource

• https://api.example.com/v1/cli/status/: Smarter platform status

Manifest Spec

See Smarter Manifest Specification

Kind

• Account

• ApiKey

• Chat

• PromptHistory

• PromptPluginUsage

• PromptToolCall

• LLMClient

• Plugin

• SqlConnection

• ApiConnection

• User

• Secret

Broker Model

Manifest processing depends on a abstract broker service. Brokers are implemented inside of Django Views and are responsible for mapping the verb of an http request – get, post, patch, put, delete – to the Python class containing the necessary services for the manifest kind. Brokers are responsible for the following:

• Defining a manifest file structure using a collection of Python enumerated data types along with basic Pydantic features.

• Reading and parsing a manifest document in yaml or json format

• Validating manifests, using Pydantic models that enforce format, syntax, and data and business rule validations.

• Instantiating the correct Python class for the manifest

• Implementing the services that back http requests: get, post, patch, put, delete

A brokered entity consists of the following:

• Pydantic model. This is a Pydantic model that describes the Manifest yaml document. Smarter manifests closely resemble Kubernetes manifests.

• Broker. Brokers marshal requests to the correct Broker class and method.

• Transformer. Transformers map data to/from a Smarter manifest and a Django object relational model (ORM).

• Docs url endpoints. Examples: https://platform.smarter.sh/docs/manifest/secret/ and https://platform.smarter.sh/docs/json-schema/secret/

• Kind registration

• Broker registration. The Broker class implements an enumeration of all resource Kinds.

• Json Schema docs view. Json schemas describe the Pydantic data model for the brokered resource. These are used for data-driven apps and services, such as the VS Code extension for Smarter manifests

• Manifest docs view. All brokers implement an example_manifest() method which, intuitively, generates a valid example Smarter yaml manifest for the Kind of resource.

Code samples

• Abstract broker

• Example implementation for Plugin broker

Controller Model

In cases where there exist multiple variations of a manifest kind, we use a Controller pattern to route a Broker to the correct Python subclass.

• Abstract controller

• Example implementation for Plugin controller as an example.