| Name | convo-lang JSON |
| Version |
0.5.11
JSON |
| download |
| home_page | |
| Summary | A conversational prompting and programming language |
| upload_time | 2023-12-16 21:44:37 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
ai
convo-lang
open-ai
prompt
prompt-engineering
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# convo-lang (a work in progress)
A conversational prompting and programming language.
# What is Convo-lang?
Convo-lang is a mixture between a procedural programming language, prompting template system and
conversation state management system. You can execute convo-lang in Javascript, Python,
from the command line or directly in VSCode.
Convo-lang aims to provided a uniform prompting syntax that is LLM agnostic and allows you to
store both prompts, metadata and tradition programming logic in a single file or template string.
The convo-lang syntax supports advanced features such as function calling, tool usage and vision.
The Convo-lang ecosystem consists of a parser, interpreter, Typescript/Javascript/Python libraries,
a CLI, and a vscode extension for syntax highlighting and in-editor script execution.
## Releases
- 0.5.10
- Started adding release notes 😅
- **Breaking change** - The CLI and vscode extension no longer enable vision support by default.
Use the `@enableVision` tag or add vision to the list capabilities in you config file.
- Capabilities can be enabled directly in convo scripts by using the `@capability` tag at the root
of a convo script. `@enableVision` is shorthand for `@capability vision`
- Added command mode to CLI. This allows the python package and other tools more easily to
interactively communicate with the CLI.
- Conversations can now dynamically invoke extern functions via the `dynamicFunctionCallback` property
- Added embedded string template highlighting in Python
## Packages
- @iyio/convo-lang - Contains the convo-lang parser, runtime, and a Typescript/Javascript library to use convo-lang in your application.
- @iyio/convo-lang-cli - A CLI interface that allows you to execute and parse convo-lang files.
- @iyio/convo-lang-tools - Contains the convo-lang vscode extension, which includes syntax highlighting,
in-editor script execution, script parsing, and other helpful tools for working with convo-lang.
In most cases, you will not install this package but instead install the vscode convo-lang extension.
- (pypi) convo-lang - Python package for executing convo-lang
## Installation
For use in python projects
``` sh
python -m pip install convo-lang
```
For use in a Javascript application install the @iyio/convo-lang package
``` sh
npm i @iyio/convo-lang
# To use OpenAI as a completion provider you will need to install @iyio/ai-complete and @iyio/ai-complete-openai as well
npm i @iyio/ai-complete @iyio/ai-complete-openai
```
For use on the command line install the @iyio/convo-lang-cli package
``` sh
npm i @iyio/convo-lang-cli -g
```
## VSCode extension
You will also probably want to install the vscode extension for syntax highlighting and other
developer niceties. You can install the vscode extension by searching for "convo-lang" in the
vscode extension tab.
https://marketplace.visualstudio.com/items?itemName=IYIO.convo-lang-tools
## Using convo-lang in a Python application
When using convo-lang in a Python application, you will primarily interact with Conversation objects.
Internally the Python package uses the convo-lang CLI and requires NodeJs to be installed for the CLI to function.
``` python
from datetime import datetime
from convo_lang import Conversation
convo=Conversation({
# Can be omitted when using an apiBaseUrl that does not require an API key
"apiKey":"YOUR_OPEN_AI_KEY",
# Can be used to connect to OpenAi compatible APIs such as LMStudio - https://lmstudio.ai/
#"apiBaseUrl":"http://localhost:1234/v1",
# Sets the models that are allowed to be used. The first model will be the default
"chatModel":"gpt-4-1106-preview,gpt-3.5-turbo-1106,gpt-3.5-turbo",
# Sets the model that will be used for audio tasks. The first model will be the default.
"audioModel":"whisper-1",
# Sets the model that will be used to image generation. The first model will be the default.
"imageModel":"dall-e-3",
# Sets the model that will be used to implement vision capabilities. The first model will be the default.
"visionModel":"gpt-4-vision-preview"
})
def setPinHigh(state):
print('Setting pin state to ',state)
# do some io stuff here
return {
"state":"on" if state else "off",
"time":str(datetime.now())
}
# adding setPinHigh to the conversation's callbacks allows setPinHigh to be called by functions
# defined in convo-lang
convo.callbacks['setPinHigh']=setPinHigh
convo.append(
"""*convo*
> define
//__model='gpt-3.5-turbo-1106'
__trackModel=true
# Turn the lights in the user's house on or off
> turnOnOffLights(
# The state to set the lights to
state: enum("on" "off")
) -> (
// setPinHigh will call the setPinHigh function defined in python
return(setPinHigh(eq(state "on")))
)
> system
You are a home automation assistant. please assistant the user to the best or your ability.
The current date and time is {{dateTime()}}
> user
It's time for bed, can you turn off the lights
""")
resultMessage=convo.completeAsync()
print('------ convo ------')
print(convo.convo)
print('\n\n------ messages ------')
print(convo.messages)
print('\n\n------ state ------')
print(convo.state)
print('\n\n------ syntaxMessages ------')
print(convo.syntaxMessages)
print('\n\n------ result ------')
print(resultMessage['content'])
```
## A quick note about all the Javascript
Most of the code examples not written in convo-lang are written in Javascript. I just
added support for Python and more Python specific examples and docs are coming.
## Using convo-lang in a Javascript application
When using convo-lang in a javascript application, you will primarily interact with Conversation objects.
Conversation objects store the messages of a convo script and allow new messages to be appended
and LLMs to respond to messages from the user.
``` js
import { Conversation } from '@iyio/convo-lang';
import { initRootScope, EnvParams } from '@iyio/common';
import { aiCompleteConvoModule } from '@iyio/ai-complete';
import { openAiModule } from '@iyio/ai-complete-openai';
// initRootScope is used to configure services and configuration variables
initRootScope(reg=>{
// register OpenAI configuration variables. These variates could also be stored as environment
// variables and loaded using reg.addParams(new EnvParams()).
reg.addParams({
"openAiApiKey":"YOUR_OPEN_AI_KEY",
"openAiChatModel":"gpt-4-1106-preview",
"openAiVisionModel":"gpt-4-vision-preview",
"openAiAudioModel":"whisper-1",
"openAiImageModel":"dall-e-3"
})
// EnvParams can optionally be used to load configuration variables from process.env
reg.addParams(new EnvParams());
// Registers the AiComplete module that is used to relay messages to LLMs
reg.use(aiCompleteConvoModule);
// Registers the OpenAI module that will relay messages to OpenAI
reg.use(openAiModule);
// aiCompleteLambdaModule can be used to relay messages to a lambda function for use in the browser
//reg.use(aiCompleteLambdaModule);
})
const main=async ()=>{
const convo=new Conversation();
// adding /*convo*/ before a template literal will give you convo syntax highlighting when you have
// the convo-lang vscode extension installed.
convo.append(/*convo*/`
> system
You are a friendly and very skilled fisherman. Taking a group of tourist on a fishing expedition
off the coast of Maine.
> user
What kind of clothes should I wear?
`);
// Calling completeAsync will answer the user's question using the configured LLM
await convo.completeAsync();
// The convo property of the Conversation object will be updated with the answer from the LLM
console.log(convo.convo)
// You can get a flatted view of the conversation by calling flattenAsync. The flatted version
// of the conversation contains messages with all templates populated and is suitable to be
// used to render a view of the conversation to the user.
const flat=await convo.flattenAsync();
console.log('flat',flat.messages);
}
main();
```
## Using the convo-lang extension
With the convo vscode extension installed, you can execute convo scripts directly in vscode. Just
press **(CMD+R)** to run a script.
You can also run snippets of convo scripts that are embedded in other
document types. Just highlight the convo code you want to run, open the command palette, and
search for "Complete Convo Conversation" and press enter. Then the snippet will be opened in a new
convo file and completed. This is great for quick prototyping and testing prompts in your application
without having to start your full application.
## Using the CLI
The convo CLI can be used to execute convo scripts from the command line
``` sh
# install the convo cli
npm install -g @iyio/convo-cli
# Results will be printed to stdout
convo talky-time.convo
# Results will be written to a new file named something-happened.convo
convo talky-time.convo --out something.convo
# Result will be written to the source input file. This allows you to have a continuous conversation
convo talky-time.convo --out .
```
There is currently only one way to configure the convo cli and vscode extension. This will be extended
soon to include reading configuration files from your current workspace.
## CLI and extension configuration
To allow convo to access OpenAI, create a JSON file called ~/.config/convo/convo.json and add the
following contents. Remember to replace the API key with your OpenAI api key.
``` json
{
"env":{
"openAiApiKey":"YOUR_OPEN_AI_KEY",
"openAiChatModel":"gpt-4-1106-preview",
"openAiVisionModel":"gpt-4-vision-preview",
"openAiAudioModel":"whisper-1",
"openAiImageModel":"dall-e-3"
}
}
```
## Vision
Vision capabilities can be added to any LLM that supports function calling. When vision is enabled
the convo-lang runtime will add the queryImage function to the current conversation and inject
instructions on how to use the function into the system prompt.
When the queryImage function is called an model with vision support is prompted and the result
is returned back to the non-vision capable model.
Vision capabilities must be enabled. In the example below visible is both enabled in the
constructor the Conversation and in the prompt using the `@enableVision`, but in practice only
one method of enabled vision is required.
``` js
const convo=new Conversation({capabilities:['vision']});
```
(note - the image in the example below is the cover of Abbey Road by The Beatles)
``` convo
// the @enableVision tag enables vision in the conversation
@enableVision
> user
Tell me a joke about this image
@toolId call_QuwU683taTBW7nsZNMNHPrmm
> call queryImage(
"query": "Tell me a joke about this image",
"imageUrls": [
"https://raw.githubusercontent.com/iyioio/common/main/assets/convo/lXwM70CjMOa6EC3PXBbJ.jpg"
]
)
> result
__return={"result":"Why did The Beatles cross the road? Because they knew it was the only way to get to the other side of their Abbey Road album cover!"}
> assistant
Why did The Beatles cross the road? Because they knew it was the only way to get to the other side of their Abbey Road album cover!
```
## The convo-lang syntax
The convo-lang syntax is designed to be easily readable and follows a chat-like message structure.
A convo-lang script consists of a series of messages, which can be text-based messages,
functions, or a set of top-level statements. All messages start with a header that defines the
message's type.
### Message Header
All message headers start with the (>) character followed by a role, keyword, or identifier.
### Text based messages
Text-based messages start with a header that defines the message's role. The role can be any identifier,
with the exception of top-level keyword identifiers.
Text message can include template variables
``` convo
// text based message
> user
message content
```
### Top-level statement messages
Top-level statements allow you to define variables and execute statements without calling a function.
Top-level statements must use one of the following keywords as their identifier:
- do - Used to define variables and execute statements.
- result - Used to store the result value of a function call. Result messages are typically created
by the runtime and automatically added to conversations. In most cases, you will not directly
create result messages.
- define - Used to define variables and types. Define messages are not allowed to call functions.
- debug - Used to write debug information. In most cases, you will not directly create debug messages.
- end - Explicitly ends a message and can be used to set variables related to the ended message.
``` convo
// top-level statement
> define
someVar=77
```
### Function messages
Function messages start with an identifier followed by a parameter definition and optionally a
function body.
``` convo
// function
> goFast(
speed: int
direction: enum("left" "right")
)
```
``` convo
// function with a body
> goFast(
speed: int
direction: enum("left" "right")
) -> (
print('I\'m going {{speed}} mile per hour and about to turn {{direction}}')
// reportStatus would be defined outside of convo and implemented in your language of choice.
reportStatus(speed direction)
return(switch(gt(speed 100) "I'm going Fast" "I'm driving like a grandma"))
)
```
### Extern function
To allow convo-lang to communicate with the rest of your application, you can register extern functions
that can be called at runtime by your convo scripts.
``` js
const convo=new Conversation();
convo.defineFunction({
name:'turnOnOffLights',
description:'Turn the lights in the user\'s house on or off',
// parameter types are defined using a Zod object
paramsType:z.object({
state:z.enum(['on','off']).describe('The state to set the lights to')
}),
callback:async ({state})=>{
const result=await fetch(`http://192.168.1.100:8888/api/lights/${state}`);
return {newState:result.state}
}
})
convo.append(/*convo*/`
> system
You are a home automation assistant. please assistant the user to the best or your ability
`);
// the turnOnOffLights function will be called with a state of "off"
await convo.completeAsync(/*convo*/`
> user
It's time for bed, can you turn off the lights
`);
```
### JSON Mode
When the last message in a conversation is tagged with the `@json` tag json mode is enabled for the
next completion. Custom user types can be used to define the scheme of the json that should
be returned by setting the value of the @json tag to the name of the desired type - `@json TypeName`
The json response can also be assigned to a variable by using the `@responseAssign` tag.
#### JSON mode with no scheme
``` convo
@json
@responseAssign planets
> user
List the planets in our solar system as a json array
@format json
@assign planets
> assistant
{
"planets": [
"Mercury",
"Venus",
"Earth",
"Mars",
"Jupiter",
"Saturn",
"Uranus",
"Neptune"
]
}
```
#### JSON mode with scheme
``` convo
> define
Planet = struct(
name:string
milesFromSun:number
moonCount:number
)
@json Planet[]
@responseAssign planets
> user
List the planets in our solar system as a json array
@format json
@assign planets
> assistant
[
{
"name": "Mercury",
"milesFromSun": 35980000,
"moonCount": 0
},
{
"name": "Venus",
"milesFromSun": 67240000,
"moonCount": 0
},
{
"name": "Earth",
"milesFromSun": 92960000,
"moonCount": 1
},
{
"name": "Mars",
"milesFromSun": 141600000,
"moonCount": 2
},
{
"name": "Jupiter",
"milesFromSun": 483800000,
"moonCount": 79
},
{
"name": "Saturn",
"milesFromSun": 890800000,
"moonCount": 83
},
{
"name": "Uranus",
"milesFromSun": 1784000000,
"moonCount": 27
},
{
"name": "Neptune",
"milesFromSun": 2795000000,
"moonCount": 14
}
]
```
As you can see, using custom user types gives you very fine tune control over the structure of the returned json.
### JSON Mode + Vision
Json mode can also be combined with vision messages
``` convo
@enableVision
> define
Person = struct(
name?:string
description?:string
)
@json Person[]
@responseAssign dudes
> user
Describe each person in this picture.
@toolId call_dfpKG4bnDRA3UTBjspQr2O4s
> call queryImage(
"query": "describe each person in this picture",
"imageUrls": [
"https://raw.githubusercontent.com/iyioio/common/main/assets/convo/lXwM70CjMOa6EC3PXBbJ.jpg"
]
)
> result
__return={
"result": "The image shows four individuals crossing the street in single file on a zebra crossing. They are all adult males, and they appear to be dressed in distinct styles:\n\n1. The first person, walking from right to left, has long hair and is wearing a white suit. He is barefoot and steps off with his right foot onto the crossing.\n\n2. The second individual has darker hair and is wearing a black suit with a white shirt and no tie. He is also stepping off with his right foot, wearing black shoes.\n\n3. The third man is wearing a suit as well, looking somewhat casually dressed compared to the second person. He has a beard and long hair and is wearing an open neck shirt with a black suit, and he is mid-step onto the zebra with his left foot forward, wearing black shoes.\n\n4. The fourth man brings up the rear and is dressed most casually. He wears a denim jacket and jeans with a white shirt underneath. He has shoulder-length hair and is taking a step with his right foot, wearing dark-colored shoes.\n\nThe setting appears to be a quiet, tree-lined street with cars parked on either side, and there is a white Volkswagen Beetle and a black car visible behind them, among other vehicles. The architecture in the background suggests this might be a residential area. The image has a calm, orderly feel, indicative of an everyday urban scene albeit with a touch of timeless style."
}
@format json
@assign dudes
> assistant
[
{
"name": "first person",
"description": "The first person, walking from right to left, has long hair and is wearing a white suit. He is barefoot and steps off with his right foot onto the crossing."
},
{
"name": "second person",
"description": "The second individual has darker hair and is wearing a black suit with a white shirt and no tie. He is also stepping off with his right foot, wearing black shoes."
},
{
"name": "third person",
"description": "The third man is wearing a suit as well, looking somewhat casually dressed compared to the second person. He has a beard and long hair and is wearing an open neck shirt with a black suit, and he is mid-step onto the zebra with his left foot forward, wearing black shoes."
},
{
"name": "fourth person",
"description": "The fourth man brings up the rear and is dressed most casually. He wears a denim jacket and jeans with a white shirt underneath. He has shoulder-length hair and is taking a step with his right foot, wearing dark-colored shoes."
}
]
```
### Comments
Comments start with either a pound character (#) or two forward slashes (//). Comments starting with a pound
symbol are captured and available at runtime as part of type definitions. Comments starting with
two forward slashes are non-capturing.
``` convo
// This is a non documenting comment and will not be available at run time
# This is a documenting comment and will be available at run time and will be used as the
# description for the function below
> meFunc() -> (
print('👋')
)
```
### Tags
Tags start with the (@) character followed by a name and an optional value. Tags allow you to
store metadata in the syntax tree of convo that is available at runtime and some special tags
control the behavior of convo-lang.
``` convo
@owner me
> meFunc() -> (
// the shared tag is a special tag that allows variables in functions to be defined in
// the shared variable scope instead of the local function scope.
@shared
somethingWeAllShouldKnow="Fish are cool"
)
@responseFormat json
> user
How many fish are in the sea
```
### Reserved tags
- @disableAutoComplete - When applied to a function the return value of the function will not be
used to generate a new assistant message.
- @edge - Used to indicate that a message should be evaluated at the edge of a conversation with
the latest state. @edge is most commonly used with system message to ensure that all injected values
are updated with the latest state of the conversation.
- @time - Used to track the time messages are created.
- @tokenUsage - Used to track the number of tokens a message used
- @model - Used to track the model used to generate completions
- @responseModel - Sets the requested model to complete a message with
- @endpoint - Used to track the endpoint to generate completions
- @responseEndpoint - Sets the requested endpoint to complete a message with
- @responseFormat - Sets the format as message should be responded to with.
- @responseAssign - Causes the response of the tagged message to be assigned to a variable
- @json - When used with a message the json tag is short and for `@responseFormat json`
- @format - The format of a message
- @assign - Used to assign the content or jsonValue of a message to a variable
- @capability - Used to enable capabilities. The capability tag can only be used on the first
message of the conversation if used on any other message it is ignored. Multiple capability tags
can be applied to a message and multiple capabilities can be specified by separating them with a comma.
- @enableVision - Shorthand for `@capability vision`
### Strings
There are 3 types of string in convo.
#### ( " ) Double quote
Double quote strings are the simplest strings in convo, they start and end with a double
quote character. To include a double quote character in a double quote string escape it with a
back slash. Double quote strings can span multiple lines.
``` convo
> define
var1="here is a double quote string"
var2="Here is a double quote string with a (\") double quote character"
var3="Here is a string with a newline
in it"
```
#### ( ' ) Single quote
Single quote strings are similar to double quote but also support embedded statements. Embedded
statements are surrounded with double curly bracket pairs and contain any valid convo statement
``` convo
> define
name="Ricky Bobby"
var0='I need to tell you something {{name}}. You can walk.'
var1='here is a single quote string'
var2='Here is a single quote string with a (\') single quote character'
var3='Here is a string with a newline
in it'
```
#### Heredoc
Heredoc strings begin and end with 3 dashes and the contents of the string are highlighted with the
convo-lang syntax highlighter but are not. They are useful when defining strings with conversation
messages in them.
``` convo
> define
var1=---
Here is a heredoc string with an conversation in it
> user
Tell me a joke about airplanes
> assistant
Why don't airlines ever play hide and seek?
Because good luck hiding a plane!
---
```
### Runtime configuration variables
Many of the configuration options of convo can be configure at runtime in directly in a convo file,
including debugging and metadata information.
- __debug - Causes extra debugging information to be printed as comments
- __trackTime - Causes the @time tag to be added to messages with the date the message was appended
- __trackTokenUsage - Causes the @tokenUsage tag to be added to messages that consume tokens
- __trackModel - Causes the @model tag to be added to generated message with the model used to generate the message
- __endpoint - Sets the default completion endpoint
- __cwd - In environments that have access to the filesystem __cwd defines the current working directory.
- __model - Sets the default completion model
- __visionSystemMessage - When defined __visionSystemMessage will be injected into the system message of conversations
with vision capabilities. __visionSystemMessage will override the default vision system message.
- __visionServiceSystemMessage - The default system message used for completing vision requests. Vision requests are typically
completed in a separate conversation that supports vision messages. By default the system
message of the conversation that triggered the vision request will be used.
- __defaultVisionResponse - Response used with the system is not able to generate a vision response.
The example below enables debugging and all trackers
``` convo
> user
Tell me a joke about airplanes
> define
__debug=true
__trackTime=true
__trackTokenUsage=true
__trackModel=true
> debug
// snd > OpenAi.ChatCompletionCreateParams
// { .... raw api message .... }
> debug
// rec < OpenAi.ChatCompletionCreateParams
// { .... raw api message .... }
@time 2023-12-11T01:31:13-05:00
@tokenUsage 139 / 33 / $0.00238
@model gpt-4-1106-preview
> assistant
Sure, here's a light-hearted airplane joke for you:
Why don't airplanes ever get tired?
Because they always have plenty of rest in the hangar!
> user
```
### Types
Convo supports simple duck typing and allows for user-defined types. User-defined types are created using
the struct function. Each labeled parameter passed to the struct function will define a property.
At runtime, types are validated using [Zod](https://github.com/colinhacks/zod). User-defined
types must start with an uppercase letter.
``` convo
Car = struct(
color: string
engine: struct(
hp: number
torque: number
fuel: enum( "gas" "diesel" "jp-7" )
)
owners: array(struct(
name: string
// address is optional
address?: string
))
)
```
### Variable scoping
Variables are either scoped to the function in which they are defined or shared. Shared variables are
visible to all functions and top-level statements. Top-level statements can only define shared
variables. To define a shared variable in a function, tag an assignment statement with the @shared
tag.
### JSON support
JSON-style values can be used in place of the map and array functions.
``` convo
// obj1 and obj2 are the same
obj1 = map(
go: "fast"
turn: "left"
times: 1000
)
obj2 = {
"go": "fast",
"turn": "left",
"times" 1000
}
```
### Markdown support - (coming soon)
Text-based messages in convo support a subset of the markdown syntax, and the markdown structure
is available at compile time.
## Keywords
- string - String type object
- number - Number type object
- int - Integer type object
- time - Time type object. The time type is represented as an integer timestamp
- void - Void type object.
- boolean - Boolean type object.
- any - Any time object
- true - True constant
- false - False constant
- null - Null constant
- undefined - Undefined constant
- convo - A reference to the current conversation. This is equivalent to window in Javascript.
- __args - A reference to the parameters passed the the current function as any object.
- __return - A reference to the last return value of a function called by a call message
- __error - A reference to the last error
## System Functions
### pipe( ...values: any )
Pipes the value of each argument received to the argument to its right.
### struct( ...properties: any )
Defines a user defined type
``` convo
Car = struct(
color: string
engine: struct(
hp: number
torque: number
fuel: enum( "gas" "diesel" "jp-7" )
)
owners: array(struct(
name: string
// address is optional
address?: string
))
)
```
### enum( ...values: any )
Defines an enumeration
``` convo
Size = enum( "sm" "md" "lg" )
```
### is( ...value:any type:any )
Checks if all of the parameters left of the last parameter are of the type of the last parameter
``` convo
num = 7
// true
is(num number)
// false
is(num string)
str = "lo"
// true
is(str string)
// false
is(str number)
// false
is(str num number)
// true
is(str num any)
Person = struct(
name: string
age: number
)
user1 = map(
name: "Jeff"
age: 22
)
user2 = map(
name: "Max"
age: 12
)
// true
is(user1 Person)
// true
is(user1 user2 Person)
// false
is(user1 user2 num Person)
```
### map( ...properties: any )
Creates an object
``` convo
// meObj has 2 properties, name and age
meObj = map(
name: "Jeff"
age: 22
)
```
### array( ...values: any )
Creates an array
``` convo
meAry = array( 1 2 3 "a" "b" "c" )
```
### jsonMap( ...properties: any )
Used internally to implement JSON object syntax support. At compile time JSON objects are converted
to standard convo function calls.
``` convo
jsonStyle = {
"go": "fast",
"turn": "left",
"times" 1000
}
convoStyle = obj1 = jsonMap(
go: "fast"
turn: "left"
times: 1000
)
```
### jsonMap( ...properties: any )
Used internally to implement JSON array syntax support. At compile time JSON arrays are converted
to standard convo function calls.
``` convo
jsonStyle = [ 1, 2, 3, "a", "b", "c" ]
convoStyle = array( 1 2 3 "a" "b" "c" )
```
### and( ...values: any )
Returns true if all given arguments are truthy.
``` convo
// true
and( 1 )
// false
and( 0 )
// true
and( 1 2 )
// false
and( 0 1 )
// true
and( eq(1 1) eq(2 2) )
// false
and( eq(1 1) eq(2 1) )
```
### or( ...values: any )
Returns the first truthy value or the last non truthy value if no truthy values are given. If no
values are given undefined is returned.
``` convo
// 1
or( 1 )
// 0
or( 0 )
// 1
or( 1 2 )
// 2
or( 0 2 )
// true
or( eq(1 1) eq(2 2) )
// true
or( eq(1 1) eq(2 1) )
// false
or( eq(1 3) eq(2 1) )
```
### not( ...values: any )
Returns true if all given arguments are falsy.
``` convo
// false
or( true )
// true
or( false )
// false
or( 1 )
// true
or( 0 )
// false
or( 1 2 )
// false
or( 0 1 )
// true
or( 0 false )
// false
or( eq(1 1))
// true
or( eq(1 2) )
```
## Control flow functions
### if( condition:any ), elif( condition: any ), then( ...statements )
If condition is truthy then the statement directly after the if statement will be executed otherwise
the statement directly after if is skipped
``` convo
age = 36
if( gte( age 21 ) ) then (
print( "You can buy beer in the US" )
) elif (lt( age 16 )) then(
print( "You're not even close" )
) else (
print( '{{sub(21 age)}} years until you can buy beer in the US' )
)
```
### while( condition:any )
While condition is truthy then the statement directly after the while statement will be executed
otherwise the statement directly after if is skipped and the while loop will exit.
``` convo
lap = 0
while( lt( lap 500 ) ) do (
print("go fast")
print("turn left")
// increment by 1
inc(lap)
)
```
### foreach( iterator:any )
Executes the next statement for each item returned by the passed in iterator.
``` convo
total = 0
foreach( num=in(array(1 2 3 4 )) ) do (
total = add( num total )
)
// 10
print(total)
```
### in( value: array(any) )
Iterates of the values of an array
### break( ...values: any )
Breaks out of loops either not arguments are passed or if any of the passed arguments are truthy
``` convo
lap = 0
while( true ) do (
print("go fast")
print("turn left")
// increment by 1
inc(lap)
if( eq( lap 500 ) ) then (
break()
)
)
```
### do( ...statements: any)
Executes all given statements and returns the value of the last statement. Do is commonly used with
loop statements, but it can also be useful in other situations on its own such as doing inline
calculations.
(note) The do keyword is also used to define top level statement when do is used as a message name.
``` convo
n = 0
while( lt( n 10 ) ) do (
// increment by 1
inc(lap)
)
// 22
print( add( 5 do(
sum = mul(n 2)
sum = sub( sum 3 )
)) )
```
### return( value:any )
Returns a value from the current function
``` convo
> customMath(
a: number
b: number
) -> (
return mul( add(a b) b )
)
> do
value = customMath(a:4 b:3)
// 21
print(value)
```
### eq( ...values:any )
Returns true if all given values are equal. Object equality is checked by by reference. Values must
be of the same type to be equal. ( a === b )
``` convo
// true
eq( 1 1 )
// false
eq( 1 "1" )
```
### gt( a:number b:number)
Returns true if a is grater then b. ( a > b )
### gte( a:number b:number)
Returns true if a is grater then or equal to b. ( a >= b )
### lt( a:number b:number)
Returns true if a is less then b. ( a < b )
### lte( a:number b:number)
Returns true if a is less then or equal to b. ( a <= b )
### add( ...values:any )
Adds all arguments together and returns the result. Strings are concatenated. (a + b )
### sub( a:number b:number )
Subtracts a from b and returns the result. (a - b )
### sub( a:number b:number )
Multiplies a and b and returns the result. (a * b )
### div( a:number b:number )
Divides a and b and returns the result. (a / b )
### pow( a:number b:number )
Raises a by b and returns the result. Math.pow(a, b )
### inc( *a:number byValue?:number )
Increments the value of the given variable by 1 or the value of the second argument. ( a++ ) or ( a+= byValue )
### dec( *a:number byValue?:number )
Decrements the value of the given variable by 1 or the value of the second argument. ( a-- ) or ( a-= byValue )
### print( ...values:any )
Prints all values to stdout
### switch( value:any ...valueOrCase:any ), case( value:any ), test( condition:any ), default()
Switch can be used as either and switch statement or a ternary. When the switch function has exactly
3 arguments and non of the is a case or default statement then switch acts as a ternary.
``` convo
// can be 0 to 9
value = rand(9)
// can be 20 to 29
value2 = add(20 rand(9))
switch(
// Sets the current match value of the switch. The match value of a switch statement can be
// changed further down the switch
value
case(0) print("Lowest")
case(1) do(
print("Value is 1")
)
case(2) do(
print("Number two")
)
case(3) do(
print("Tree or three")
)
// change the value to a value in ary
value2
case(20) do(
print("2 zero")
)
test(lt(value2 28)) do(
print("less than 28")
)
default() print("Fall back to default")
)
// values matched by switches are returned and the value can be assigned to a variable
str = "two"
value = switch(
str
case("one") 1
case("two") 2
case("three") 3
)
// 2
print(value)
// switches can also be used as a ternary
// yes
print( switch(true "yes" "no") )
// no
print( switch(false "yes" "no") )
```
### now()
Returns the current date time as a timestamp. now uses Date.now() to get the current timestamp.
### dateTime( format?:string date?:string|number|Date )
Returns the current or given date as a formatted string. The default value format string is
"yyyy-MM-dd'T'HH:mm:ssxxx" which is an ISO 8601 date and results in formatted dates that look
like 2023-12-08T21:05:08-01:00. Invalid date formats will fallback to using the default date format.
Formatting is done using date-fns - https://date-fns.org/v2.16.1/docs/format
### sleep( milliseconds:number )
Suspends execution for the given number of milliseconds
### rand( max?:int )
Returns a random number. Is the max parameters is passed then a random whole number with a
maximum of max will be returned otherwise a random number from 0 to 1 will be returned.
### httpGet( url:string )
Performs an http GET request and returns the parsed JSON result. Results with a 404 status or a
Content-Type not equal to application/json are returned as undefined.
### httpGetString( url: string )
Performs an http GET request and returns the result as a string.
### httpPost( url:string body:any )
Performs an http POST request and returns the parsed JSON result. Results with a 404 status or a
Content-Type not equal to application/json are returned as undefined.
### httpPatch( url:string body:any )
Performs an http PATCH request and returns the parsed JSON result. Results with a 404 status or a
Content-Type not equal to application/json are returned as undefined.
### httpPut( url:string body:any )
Performs an http PUT request and returns the parsed JSON result. Results with a 404 status or a
Content-Type not equal to application/json are returned as undefined.
### httpDelete( url:string )
Performs an http DELETE request and returns the parsed JSON result. Results with a 404 status or a
Content-Type not equal to application/json are returned as undefined.
### encodeURI( value:string )
Returns the value encoded as an URI
### encodeURIComponent( value:string )
Returns the value encoded as an URI component
### md( ...values:any[] )
Concatenates all passed in values and formats the values as markdown. Recursive objects are limited
to a depth of 5.
### toMarkdown( maxDepth:int value:any)
formats the value as markdown and allows the configuration of recursive object depth.
### toJson( value:any )
Formats the given value as json
### toJsonMdBlock( value:any )
Formats the given value as json and closes the value in a markdown json code block.
### toJsonScheme( type:struct )
Prints a struct as a JSON scheme.
### toCsv( value:any[] )
Prints an array of values a as CSV.
### toCsvMdBlock
Prints an array of values a as CSV inside of a markdown code block.
### merge( ...values:any[] )
Merges all passed in parameters into a single object. merge is similar to Javascript's spread operator.
## Examples
Since NPM and GitHub do not support custom syntax highlighters the examples below include both the
code for each example and an image showing syntax highlighting.
### Get Weather
``` convo
> define
// Yes, this is a real api key. Be considerate and dont abuse it, but if some body does and rate
// limits are hit you can get your own TomorrowIo api at https://www.tomorrow.io/
tomorrowIoApiKey="epYQMxHaP4r47kOeKZbomUBZN6oLwP8h"
# Gets the current weather conditions for the given location. Returned values use the metric system.
> getWeather(
# The location to get weather conditions for
location:string
) -> (
weather=httpGet('https://api.tomorrow.io/v4/weather/realtime?location={{
encodeURIComponent(location)
}}&apikey={{tomorrowIoApiKey}}')
return(weather)
)
> user
What is the temperature and wind speed in New York city?
@toolId call_iKoMeLGDuZln9mtR20CbkJiM
> call getWeather(
"location": "New York"
)
> result
__return={
"data": {
"time": "2023-12-05T20:57:00Z",
"values": {
"cloudBase": 1.08,
"cloudCeiling": 1.08,
"cloudCover": 100,
"dewPoint": -2.81,
"freezingRainIntensity": 0,
"humidity": 53,
"precipitationProbability": 0,
"pressureSurfaceLevel": 1013.9,
"rainIntensity": 0,
"sleetIntensity": 0,
"snowIntensity": 0,
"temperature": 6,
"temperatureApparent": 6,
"uvHealthConcern": 0,
"uvIndex": 0,
"visibility": 16,
"weatherCode": 1001,
"windDirection": 257.69,
"windGust": 2.13,
"windSpeed": 1.88
}
},
"location": {
"lat": 40.71272659301758,
"lon": -74.00601196289062,
"name": "City of New York, New York, United States",
"type": "administrative"
}
}
> assistant
In New York City, the current temperature is 6°C and the wind speed is 1.88 meters per second.
```
### Calling Shell Scripts
``` convo
// (Caution) this script is capable to running shell command on you machine.
// (Note) Before commands are ran you will be prompted to allow access to run the command and
// be given a preview of the command
> define
computerType="MacBook pro"
# Runs a command in a bash shell
> runCommand(
# the command to run
command:string
) -> (
__cwd="/Users/scott/docs/iyio-common/packages"
print('running...' command)
return(exec(command))
)
> system
You are a Unix systems expert. Always use the runCommand function when responding.
The user has a {{computerType}}
> user
Create a new file called bobs-my-uncle.txt and add the text "I like fish frogs" to it
```
### Zoo Builder
``` convo
// Top level statements defining shared variables and custom user types. Top level statements
// start with (> define), (> do) or (> result)
> define
location = "Cincinnati, OH"
Animal = struct(
species: string
# Weight in pounds
weight: int
type: enum( "carnivore" "omnivore" "herbivore")
# Price in USD to buy the animal
price: number
)
// This is a function that can be called by an LLM
# Builds a new exhibit featuring a collection of animals
> buildExhibit(
# The featured animals
animals: array(Animal)
# Price in USD to build the exhibit excluding the animals
price: number
# The size of the exhibit in square feet
size: number
# A short description of the exhibit
description: string
) -> (
print('Building new exhibit with {{animals.length}} animals')
totalPrice = price
foreach( a=in(animals) ) do (
// Uncomment the line below after you provide an extern function for buyAnimal
//buyAnimal(a)
inc(totalPrice a.price)
)
return(map(
animalsBought: animals.length
totalPrice: totalPrice
success: true
))
)
// This function is not visible to LLMs and will be used to call an extern function
// defined in Javascript
> local buyAnimal(animal:Animal)
// This is a system prompt that tells the LLM who they are
> system
You are a funny and helpful zoo keeper helping the user build a new zoo. The zoo is located
in {{location}}.
// This is a user prompt that the LLM will respond to
> user
The Bengals are going to be sponsoring the zoo this year. Lets build an exhibit they will like.
Response using the buildExhibit function
// This is a function call return by the LLM
> call buildExhibit(
"animals": [
{
"species": "Bengal Tiger",
"weight": 420,
"type": "carnivore",
"price": 20000
},
{
"species": "White Bengal Tiger",
"weight": 400,
"type": "carnivore",
"price": 25000
},
{
"species": "Bengal Fox",
"weight": 20,
"type": "omnivore",
"price": 5000
}
],
"price": 1500000,
"size": 50000,
"description": "A mesmerizing tribute to the wild beauty of Bengal, the 'Bengals' Kingdom' features stunning Bengal Tigers, including the rare and captivating White Bengal Tiger, and the cunning Bengal Fox. The Bengals' Kingdom spans 50,000 square feet, providing plenty of prowling room for the resident animals. Bengals' fans and animal lovers alike will enjoy this enchanting walk on the wild side!"
)
> result
// Value return by the call to buildExhibit
__return={"animalsBought":3,"totalPrice":1550000,"success":true}
// Response from the LLM based on the return value of buildExhibit
> assistant
Great news! We've successfully built the 'Bengals' Kingdom'!
Here's a sneak peek:
- It's home to the magnificent Bengal Tiger, the rare White Bengal Tiger, and the wily Bengal Fox.
- The exhibit is an enormous 50,000 square feet! That's gonna be a lot of tiger prowling action!
- And the total cost, including our new furry residents? A cool $1,550,000. Yes, tigers are a bit on the pricier side, but hey, they're worth every penny.
Would you like to add anything else to our new zoo?
```
### More examples
More examples can be found at https://github.com/iyioio/common/tree/main/packages/convo-lang-tools/examples
Raw data
{
"_id": null,
"home_page": "",
"name": "convo-lang",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "ai,convo-lang,open-ai,prompt,prompt-engineering",
"author": "",
"author_email": "Scott Vance <scott@iyio.io>",
"download_url": "https://files.pythonhosted.org/packages/d5/84/7a0a08a72af418f54918956201ce51c5fb3b6ffe9883929edb3e9594a588/convo_lang-0.5.11.tar.gz",
"platform": null,
"description": "# convo-lang (a work in progress)\nA conversational prompting and programming language.\n\n\n\n# What is Convo-lang?\nConvo-lang is a mixture between a procedural programming language, prompting template system and \nconversation state management system. You can execute convo-lang in Javascript, Python,\nfrom the command line or directly in VSCode.\n\nConvo-lang aims to provided a uniform prompting syntax that is LLM agnostic and allows you to\nstore both prompts, metadata and tradition programming logic in a single file or template string.\n\nThe convo-lang syntax supports advanced features such as function calling, tool usage and vision.\nThe Convo-lang ecosystem consists of a parser, interpreter, Typescript/Javascript/Python libraries,\na CLI, and a vscode extension for syntax highlighting and in-editor script execution.\n\n## Releases\n- 0.5.10\n - Started adding release notes \ud83d\ude05\n - **Breaking change** - The CLI and vscode extension no longer enable vision support by default. \n Use the `@enableVision` tag or add vision to the list capabilities in you config file.\n - Capabilities can be enabled directly in convo scripts by using the `@capability` tag at the root\n of a convo script. `@enableVision` is shorthand for `@capability vision`\n - Added command mode to CLI. This allows the python package and other tools more easily to\n interactively communicate with the CLI.\n - Conversations can now dynamically invoke extern functions via the `dynamicFunctionCallback` property\n - Added embedded string template highlighting in Python\n\n\n## Packages\n- @iyio/convo-lang - Contains the convo-lang parser, runtime, and a Typescript/Javascript library to use convo-lang in your application.\n- @iyio/convo-lang-cli - A CLI interface that allows you to execute and parse convo-lang files.\n- @iyio/convo-lang-tools - Contains the convo-lang vscode extension, which includes syntax highlighting,\n in-editor script execution, script parsing, and other helpful tools for working with convo-lang.\n In most cases, you will not install this package but instead install the vscode convo-lang extension.\n- (pypi) convo-lang - Python package for executing convo-lang\n\n\n## Installation\n\nFor use in python projects\n``` sh\npython -m pip install convo-lang\n```\n\nFor use in a Javascript application install the @iyio/convo-lang package\n``` sh\nnpm i @iyio/convo-lang\n\n# To use OpenAI as a completion provider you will need to install @iyio/ai-complete and @iyio/ai-complete-openai as well\nnpm i @iyio/ai-complete @iyio/ai-complete-openai\n```\n\nFor use on the command line install the @iyio/convo-lang-cli package\n``` sh\nnpm i @iyio/convo-lang-cli -g\n```\n\n## VSCode extension\nYou will also probably want to install the vscode extension for syntax highlighting and other\ndeveloper niceties. You can install the vscode extension by searching for \"convo-lang\" in the\nvscode extension tab.\n\nhttps://marketplace.visualstudio.com/items?itemName=IYIO.convo-lang-tools \n\n\n\n## Using convo-lang in a Python application\nWhen using convo-lang in a Python application, you will primarily interact with Conversation objects.\nInternally the Python package uses the convo-lang CLI and requires NodeJs to be installed for the CLI to function.\n\n``` python\nfrom datetime import datetime\nfrom convo_lang import Conversation\n\nconvo=Conversation({\n # Can be omitted when using an apiBaseUrl that does not require an API key\n \"apiKey\":\"YOUR_OPEN_AI_KEY\",\n\n # Can be used to connect to OpenAi compatible APIs such as LMStudio - https://lmstudio.ai/ \n #\"apiBaseUrl\":\"http://localhost:1234/v1\",\n\n # Sets the models that are allowed to be used. The first model will be the default\n \"chatModel\":\"gpt-4-1106-preview,gpt-3.5-turbo-1106,gpt-3.5-turbo\",\n\n # Sets the model that will be used for audio tasks. The first model will be the default.\n \"audioModel\":\"whisper-1\",\n\n # Sets the model that will be used to image generation. The first model will be the default.\n \"imageModel\":\"dall-e-3\",\n\n # Sets the model that will be used to implement vision capabilities. The first model will be the default.\n \"visionModel\":\"gpt-4-vision-preview\"\n})\n\n\ndef setPinHigh(state):\n\n print('Setting pin state to ',state)\n\n # do some io stuff here\n\n return {\n \"state\":\"on\" if state else \"off\",\n \"time\":str(datetime.now())\n }\n\n# adding setPinHigh to the conversation's callbacks allows setPinHigh to be called by functions\n# defined in convo-lang\nconvo.callbacks['setPinHigh']=setPinHigh\n\nconvo.append(\n\"\"\"*convo*\n> define\n//__model='gpt-3.5-turbo-1106'\n__trackModel=true\n\n# Turn the lights in the user's house on or off\n> turnOnOffLights(\n # The state to set the lights to\n state: enum(\"on\" \"off\")\n) -> (\n\n // setPinHigh will call the setPinHigh function defined in python\n return(setPinHigh(eq(state \"on\")))\n)\n\n> system\nYou are a home automation assistant. please assistant the user to the best or your ability.\n\nThe current date and time is {{dateTime()}}\n\n> user\nIt's time for bed, can you turn off the lights\n\n\"\"\")\n\nresultMessage=convo.completeAsync()\n\nprint('------ convo ------')\nprint(convo.convo)\n\nprint('\\n\\n------ messages ------')\nprint(convo.messages)\n\nprint('\\n\\n------ state ------')\nprint(convo.state)\n\nprint('\\n\\n------ syntaxMessages ------')\nprint(convo.syntaxMessages)\n\nprint('\\n\\n------ result ------')\nprint(resultMessage['content'])\n\n```\n\n\n## A quick note about all the Javascript\nMost of the code examples not written in convo-lang are written in Javascript. I just\nadded support for Python and more Python specific examples and docs are coming.\n\n\n## Using convo-lang in a Javascript application\nWhen using convo-lang in a javascript application, you will primarily interact with Conversation objects.\nConversation objects store the messages of a convo script and allow new messages to be appended\nand LLMs to respond to messages from the user.\n\n``` js\nimport { Conversation } from '@iyio/convo-lang';\nimport { initRootScope, EnvParams } from '@iyio/common';\nimport { aiCompleteConvoModule } from '@iyio/ai-complete';\nimport { openAiModule } from '@iyio/ai-complete-openai';\n\n// initRootScope is used to configure services and configuration variables\ninitRootScope(reg=>{\n\n // register OpenAI configuration variables. These variates could also be stored as environment\n // variables and loaded using reg.addParams(new EnvParams()).\n reg.addParams({\n \"openAiApiKey\":\"YOUR_OPEN_AI_KEY\",\n \"openAiChatModel\":\"gpt-4-1106-preview\",\n \"openAiVisionModel\":\"gpt-4-vision-preview\",\n \"openAiAudioModel\":\"whisper-1\",\n \"openAiImageModel\":\"dall-e-3\"\n })\n\n // EnvParams can optionally be used to load configuration variables from process.env\n reg.addParams(new EnvParams());\n\n // Registers the AiComplete module that is used to relay messages to LLMs\n reg.use(aiCompleteConvoModule);\n\n // Registers the OpenAI module that will relay messages to OpenAI\n reg.use(openAiModule);\n\n // aiCompleteLambdaModule can be used to relay messages to a lambda function for use in the browser\n //reg.use(aiCompleteLambdaModule);\n})\n\nconst main=async ()=>{\n const convo=new Conversation();\n\n // adding /*convo*/ before a template literal will give you convo syntax highlighting when you have\n // the convo-lang vscode extension installed.\n\n convo.append(/*convo*/`\n > system\n You are a friendly and very skilled fisherman. Taking a group of tourist on a fishing expedition\n off the coast of Maine.\n\n > user\n What kind of clothes should I wear?\n `);\n\n // Calling completeAsync will answer the user's question using the configured LLM\n await convo.completeAsync();\n\n\n // The convo property of the Conversation object will be updated with the answer from the LLM\n console.log(convo.convo)\n\n // You can get a flatted view of the conversation by calling flattenAsync. The flatted version\n // of the conversation contains messages with all templates populated and is suitable to be \n // used to render a view of the conversation to the user.\n const flat=await convo.flattenAsync();\n console.log('flat',flat.messages);\n}\n\nmain();\n\n```\n\n## Using the convo-lang extension\nWith the convo vscode extension installed, you can execute convo scripts directly in vscode. Just\npress **(CMD+R)** to run a script.\n\nYou can also run snippets of convo scripts that are embedded in other\ndocument types. Just highlight the convo code you want to run, open the command palette, and\nsearch for \"Complete Convo Conversation\" and press enter. Then the snippet will be opened in a new\nconvo file and completed. This is great for quick prototyping and testing prompts in your application\nwithout having to start your full application.\n\n## Using the CLI\nThe convo CLI can be used to execute convo scripts from the command line\n\n``` sh\n# install the convo cli\nnpm install -g @iyio/convo-cli\n\n# Results will be printed to stdout\nconvo talky-time.convo\n\n# Results will be written to a new file named something-happened.convo\nconvo talky-time.convo --out something.convo\n\n# Result will be written to the source input file. This allows you to have a continuous conversation\nconvo talky-time.convo --out .\n```\n\nThere is currently only one way to configure the convo cli and vscode extension. This will be extended\nsoon to include reading configuration files from your current workspace. \n\n\n## CLI and extension configuration\nTo allow convo to access OpenAI, create a JSON file called ~/.config/convo/convo.json and add the\nfollowing contents. Remember to replace the API key with your OpenAI api key.\n\n``` json\n{\n \"env\":{\n \"openAiApiKey\":\"YOUR_OPEN_AI_KEY\",\n \"openAiChatModel\":\"gpt-4-1106-preview\",\n \"openAiVisionModel\":\"gpt-4-vision-preview\",\n \"openAiAudioModel\":\"whisper-1\",\n \"openAiImageModel\":\"dall-e-3\"\n\n }\n}\n```\n\n## Vision\nVision capabilities can be added to any LLM that supports function calling. When vision is enabled\nthe convo-lang runtime will add the queryImage function to the current conversation and inject \ninstructions on how to use the function into the system prompt.\n\nWhen the queryImage function is called an model with vision support is prompted and the result\nis returned back to the non-vision capable model.\n\nVision capabilities must be enabled. In the example below visible is both enabled in the \nconstructor the Conversation and in the prompt using the `@enableVision`, but in practice only \none method of enabled vision is required.\n``` js\nconst convo=new Conversation({capabilities:['vision']});\n```\n\n(note - the image in the example below is the cover of Abbey Road by The Beatles)\n``` convo\n// the @enableVision tag enables vision in the conversation\n@enableVision\n> user\nTell me a joke about this image\n\n\n\n@toolId call_QuwU683taTBW7nsZNMNHPrmm\n> call queryImage(\n \"query\": \"Tell me a joke about this image\",\n \"imageUrls\": [\n \"https://raw.githubusercontent.com/iyioio/common/main/assets/convo/lXwM70CjMOa6EC3PXBbJ.jpg\"\n ]\n)\n> result\n__return={\"result\":\"Why did The Beatles cross the road? Because they knew it was the only way to get to the other side of their Abbey Road album cover!\"}\n\n\n> assistant\nWhy did The Beatles cross the road? Because they knew it was the only way to get to the other side of their Abbey Road album cover!\n\n```\n\n## The convo-lang syntax\nThe convo-lang syntax is designed to be easily readable and follows a chat-like message structure.\nA convo-lang script consists of a series of messages, which can be text-based messages,\nfunctions, or a set of top-level statements. All messages start with a header that defines the\nmessage's type.\n\n### Message Header\nAll message headers start with the (>) character followed by a role, keyword, or identifier.\n\n### Text based messages\nText-based messages start with a header that defines the message's role. The role can be any identifier,\nwith the exception of top-level keyword identifiers.\n\nText message can include template variables\n\n``` convo\n// text based message\n> user\nmessage content\n```\n\n### Top-level statement messages\nTop-level statements allow you to define variables and execute statements without calling a function.\nTop-level statements must use one of the following keywords as their identifier:\n\n- do - Used to define variables and execute statements.\n- result - Used to store the result value of a function call. Result messages are typically created\n by the runtime and automatically added to conversations. In most cases, you will not directly\n create result messages.\n- define - Used to define variables and types. Define messages are not allowed to call functions.\n- debug - Used to write debug information. In most cases, you will not directly create debug messages.\n- end - Explicitly ends a message and can be used to set variables related to the ended message.\n\n``` convo\n// top-level statement\n> define\nsomeVar=77\n```\n\n### Function messages\nFunction messages start with an identifier followed by a parameter definition and optionally a\nfunction body.\n\n``` convo\n// function\n> goFast(\n speed: int\n direction: enum(\"left\" \"right\")\n)\n```\n\n``` convo\n// function with a body\n> goFast(\n speed: int\n direction: enum(\"left\" \"right\")\n) -> (\n print('I\\'m going {{speed}} mile per hour and about to turn {{direction}}')\n\n // reportStatus would be defined outside of convo and implemented in your language of choice.\n reportStatus(speed direction)\n\n return(switch(gt(speed 100) \"I'm going Fast\" \"I'm driving like a grandma\"))\n)\n```\n\n### Extern function\nTo allow convo-lang to communicate with the rest of your application, you can register extern functions\nthat can be called at runtime by your convo scripts.\n\n``` js\nconst convo=new Conversation();\n\nconvo.defineFunction({\n name:'turnOnOffLights',\n description:'Turn the lights in the user\\'s house on or off',\n // parameter types are defined using a Zod object\n paramsType:z.object({\n state:z.enum(['on','off']).describe('The state to set the lights to')\n }),\n callback:async ({state})=>{\n const result=await fetch(`http://192.168.1.100:8888/api/lights/${state}`);\n return {newState:result.state}\n }\n})\n\nconvo.append(/*convo*/`\n > system\n You are a home automation assistant. please assistant the user to the best or your ability\n`);\n\n// the turnOnOffLights function will be called with a state of \"off\"\nawait convo.completeAsync(/*convo*/`\n > user\n It's time for bed, can you turn off the lights\n`);\n```\n\n### JSON Mode\nWhen the last message in a conversation is tagged with the `@json` tag json mode is enabled for the \nnext completion. Custom user types can be used to define the scheme of the json that should\nbe returned by setting the value of the @json tag to the name of the desired type - `@json TypeName`\n\nThe json response can also be assigned to a variable by using the `@responseAssign` tag.\n\n#### JSON mode with no scheme\n``` convo\n@json\n@responseAssign planets\n> user\nList the planets in our solar system as a json array\n\n@format json\n@assign planets\n> assistant\n{\n \"planets\": [\n \"Mercury\",\n \"Venus\",\n \"Earth\",\n \"Mars\",\n \"Jupiter\",\n \"Saturn\",\n \"Uranus\",\n \"Neptune\"\n ]\n}\n```\n\n#### JSON mode with scheme\n``` convo\n> define\n\nPlanet = struct(\n name:string\n milesFromSun:number\n moonCount:number\n)\n\n@json Planet[]\n@responseAssign planets\n> user\nList the planets in our solar system as a json array\n\n@format json\n@assign planets\n> assistant\n[\n {\n \"name\": \"Mercury\",\n \"milesFromSun\": 35980000,\n \"moonCount\": 0\n },\n {\n \"name\": \"Venus\",\n \"milesFromSun\": 67240000,\n \"moonCount\": 0\n },\n {\n \"name\": \"Earth\",\n \"milesFromSun\": 92960000,\n \"moonCount\": 1\n },\n {\n \"name\": \"Mars\",\n \"milesFromSun\": 141600000,\n \"moonCount\": 2\n },\n {\n \"name\": \"Jupiter\",\n \"milesFromSun\": 483800000,\n \"moonCount\": 79\n },\n {\n \"name\": \"Saturn\",\n \"milesFromSun\": 890800000,\n \"moonCount\": 83\n },\n {\n \"name\": \"Uranus\",\n \"milesFromSun\": 1784000000,\n \"moonCount\": 27\n },\n {\n \"name\": \"Neptune\",\n \"milesFromSun\": 2795000000,\n \"moonCount\": 14\n }\n]\n```\n\nAs you can see, using custom user types gives you very fine tune control over the structure of the returned json.\n\n### JSON Mode + Vision\nJson mode can also be combined with vision messages\n\n``` convo\n@enableVision\n> define\nPerson = struct(\n name?:string\n description?:string\n)\n\n@json Person[]\n@responseAssign dudes\n> user\nDescribe each person in this picture.\n\n\n\n\n@toolId call_dfpKG4bnDRA3UTBjspQr2O4s\n> call queryImage(\n \"query\": \"describe each person in this picture\",\n \"imageUrls\": [\n \"https://raw.githubusercontent.com/iyioio/common/main/assets/convo/lXwM70CjMOa6EC3PXBbJ.jpg\"\n ]\n)\n> result\n__return={\n \"result\": \"The image shows four individuals crossing the street in single file on a zebra crossing. They are all adult males, and they appear to be dressed in distinct styles:\\n\\n1. The first person, walking from right to left, has long hair and is wearing a white suit. He is barefoot and steps off with his right foot onto the crossing.\\n\\n2. The second individual has darker hair and is wearing a black suit with a white shirt and no tie. He is also stepping off with his right foot, wearing black shoes.\\n\\n3. The third man is wearing a suit as well, looking somewhat casually dressed compared to the second person. He has a beard and long hair and is wearing an open neck shirt with a black suit, and he is mid-step onto the zebra with his left foot forward, wearing black shoes.\\n\\n4. The fourth man brings up the rear and is dressed most casually. He wears a denim jacket and jeans with a white shirt underneath. He has shoulder-length hair and is taking a step with his right foot, wearing dark-colored shoes.\\n\\nThe setting appears to be a quiet, tree-lined street with cars parked on either side, and there is a white Volkswagen Beetle and a black car visible behind them, among other vehicles. The architecture in the background suggests this might be a residential area. The image has a calm, orderly feel, indicative of an everyday urban scene albeit with a touch of timeless style.\"\n}\n\n\n@format json\n@assign dudes\n> assistant\n[\n {\n \"name\": \"first person\",\n \"description\": \"The first person, walking from right to left, has long hair and is wearing a white suit. He is barefoot and steps off with his right foot onto the crossing.\"\n },\n {\n \"name\": \"second person\",\n \"description\": \"The second individual has darker hair and is wearing a black suit with a white shirt and no tie. He is also stepping off with his right foot, wearing black shoes.\"\n },\n {\n \"name\": \"third person\",\n \"description\": \"The third man is wearing a suit as well, looking somewhat casually dressed compared to the second person. He has a beard and long hair and is wearing an open neck shirt with a black suit, and he is mid-step onto the zebra with his left foot forward, wearing black shoes.\"\n },\n {\n \"name\": \"fourth person\",\n \"description\": \"The fourth man brings up the rear and is dressed most casually. He wears a denim jacket and jeans with a white shirt underneath. He has shoulder-length hair and is taking a step with his right foot, wearing dark-colored shoes.\"\n }\n]\n```\n\n### Comments\nComments start with either a pound character (#) or two forward slashes (//). Comments starting with a pound\nsymbol are captured and available at runtime as part of type definitions. Comments starting with\ntwo forward slashes are non-capturing.\n\n``` convo\n\n// This is a non documenting comment and will not be available at run time\n\n# This is a documenting comment and will be available at run time and will be used as the \n# description for the function below\n> meFunc() -> (\n print('\ud83d\udc4b')\n)\n```\n\n### Tags\nTags start with the (@) character followed by a name and an optional value. Tags allow you to\nstore metadata in the syntax tree of convo that is available at runtime and some special tags \ncontrol the behavior of convo-lang.\n\n``` convo\n@owner me\n> meFunc() -> (\n \n // the shared tag is a special tag that allows variables in functions to be defined in\n // the shared variable scope instead of the local function scope.\n @shared\n somethingWeAllShouldKnow=\"Fish are cool\"\n)\n\n@responseFormat json\n> user\nHow many fish are in the sea\n```\n\n### Reserved tags\n- @disableAutoComplete - When applied to a function the return value of the function will not be \n used to generate a new assistant message.\n- @edge - Used to indicate that a message should be evaluated at the edge of a conversation with \n the latest state. @edge is most commonly used with system message to ensure that all injected values\n are updated with the latest state of the conversation.\n- @time - Used to track the time messages are created.\n- @tokenUsage - Used to track the number of tokens a message used\n- @model - Used to track the model used to generate completions\n- @responseModel - Sets the requested model to complete a message with\n- @endpoint - Used to track the endpoint to generate completions\n- @responseEndpoint - Sets the requested endpoint to complete a message with\n- @responseFormat - Sets the format as message should be responded to with.\n- @responseAssign - Causes the response of the tagged message to be assigned to a variable\n- @json - When used with a message the json tag is short and for `@responseFormat json`\n- @format - The format of a message\n- @assign - Used to assign the content or jsonValue of a message to a variable\n- @capability - Used to enable capabilities. The capability tag can only be used on the first \n message of the conversation if used on any other message it is ignored. Multiple capability tags\n can be applied to a message and multiple capabilities can be specified by separating them with a comma.\n- @enableVision - Shorthand for `@capability vision`\n\n### Strings\nThere are 3 types of string in convo.\n\n#### ( \" ) Double quote\nDouble quote strings are the simplest strings in convo, they start and end with a double \nquote character. To include a double quote character in a double quote string escape it with a\nback slash. Double quote strings can span multiple lines.\n\n``` convo\n> define\nvar1=\"here is a double quote string\"\nvar2=\"Here is a double quote string with a (\\\") double quote character\"\nvar3=\"Here is a string with a newline\nin it\"\n```\n\n#### ( ' ) Single quote\nSingle quote strings are similar to double quote but also support embedded statements. Embedded\nstatements are surrounded with double curly bracket pairs and contain any valid convo statement\n\n``` convo\n> define\nname=\"Ricky Bobby\"\nvar0='I need to tell you something {{name}}. You can walk.'\n\nvar1='here is a single quote string'\nvar2='Here is a single quote string with a (\\') single quote character'\nvar3='Here is a string with a newline\nin it'\n```\n\n#### Heredoc\nHeredoc strings begin and end with 3 dashes and the contents of the string are highlighted with the\nconvo-lang syntax highlighter but are not. They are useful when defining strings with conversation\nmessages in them.\n\n``` convo\n> define\nvar1=---\nHere is a heredoc string with an conversation in it\n\n> user\nTell me a joke about airplanes\n\n> assistant\nWhy don't airlines ever play hide and seek?\n\nBecause good luck hiding a plane!\n---\n```\n\n### Runtime configuration variables\nMany of the configuration options of convo can be configure at runtime in directly in a convo file,\nincluding debugging and metadata information.\n\n- __debug - Causes extra debugging information to be printed as comments\n- __trackTime - Causes the @time tag to be added to messages with the date the message was appended\n- __trackTokenUsage - Causes the @tokenUsage tag to be added to messages that consume tokens\n- __trackModel - Causes the @model tag to be added to generated message with the model used to generate the message\n- __endpoint - Sets the default completion endpoint\n- __cwd - In environments that have access to the filesystem __cwd defines the current working directory.\n- __model - Sets the default completion model\n- __visionSystemMessage - When defined __visionSystemMessage will be injected into the system message of conversations \n with vision capabilities. __visionSystemMessage will override the default vision system message.\n- __visionServiceSystemMessage - The default system message used for completing vision requests. Vision requests are typically\n completed in a separate conversation that supports vision messages. By default the system\n message of the conversation that triggered the vision request will be used.\n- __defaultVisionResponse - Response used with the system is not able to generate a vision response.\n\n\nThe example below enables debugging and all trackers\n``` convo\n> user\nTell me a joke about airplanes\n\n> define\n__debug=true\n__trackTime=true\n__trackTokenUsage=true\n__trackModel=true\n\n\n> debug\n// snd > OpenAi.ChatCompletionCreateParams\n// { .... raw api message .... }\n\n> debug\n// rec < OpenAi.ChatCompletionCreateParams\n// { .... raw api message .... }\n\n@time 2023-12-11T01:31:13-05:00\n@tokenUsage 139 / 33 / $0.00238\n@model gpt-4-1106-preview\n> assistant\nSure, here's a light-hearted airplane joke for you:\n\nWhy don't airplanes ever get tired?\n\nBecause they always have plenty of rest in the hangar!\n\n\n> user\n\n```\n\n### Types\nConvo supports simple duck typing and allows for user-defined types. User-defined types are created using\nthe struct function. Each labeled parameter passed to the struct function will define a property.\nAt runtime, types are validated using [Zod](https://github.com/colinhacks/zod). User-defined\ntypes must start with an uppercase letter.\n\n``` convo\nCar = struct(\n color: string\n engine: struct(\n hp: number\n torque: number\n fuel: enum( \"gas\" \"diesel\" \"jp-7\" )\n )\n owners: array(struct(\n name: string\n // address is optional\n address?: string\n ))\n)\n```\n\n\n### Variable scoping\nVariables are either scoped to the function in which they are defined or shared. Shared variables are\nvisible to all functions and top-level statements. Top-level statements can only define shared\nvariables. To define a shared variable in a function, tag an assignment statement with the @shared\ntag.\n\n### JSON support\nJSON-style values can be used in place of the map and array functions.\n``` convo\n// obj1 and obj2 are the same\n\nobj1 = map(\n go: \"fast\"\n turn: \"left\"\n times: 1000\n)\n\nobj2 = {\n \"go\": \"fast\",\n \"turn\": \"left\",\n \"times\" 1000\n}\n```\n\n\n### Markdown support - (coming soon)\nText-based messages in convo support a subset of the markdown syntax, and the markdown structure\nis available at compile time.\n\n\n\n## Keywords\n\n- string - String type object\n- number - Number type object\n- int - Integer type object\n- time - Time type object. The time type is represented as an integer timestamp\n- void - Void type object.\n- boolean - Boolean type object.\n- any - Any time object\n- true - True constant\n- false - False constant\n- null - Null constant\n- undefined - Undefined constant\n- convo - A reference to the current conversation. This is equivalent to window in Javascript.\n- __args - A reference to the parameters passed the the current function as any object.\n- __return - A reference to the last return value of a function called by a call message\n- __error - A reference to the last error\n\n## System Functions\n\n### pipe( ...values: any )\nPipes the value of each argument received to the argument to its right.\n\n### struct( ...properties: any )\nDefines a user defined type\n\n``` convo\nCar = struct(\n color: string\n engine: struct(\n hp: number\n torque: number\n fuel: enum( \"gas\" \"diesel\" \"jp-7\" )\n )\n owners: array(struct(\n name: string\n // address is optional\n address?: string\n ))\n)\n```\n\n### enum( ...values: any )\nDefines an enumeration\n``` convo\nSize = enum( \"sm\" \"md\" \"lg\" )\n```\n\n### is( ...value:any type:any )\nChecks if all of the parameters left of the last parameter are of the type of the last parameter\n``` convo\nnum = 7\n\n// true\nis(num number)\n\n// false\nis(num string)\n\nstr = \"lo\"\n\n// true\nis(str string)\n\n// false\nis(str number)\n\n// false\nis(str num number)\n\n// true\nis(str num any)\n\nPerson = struct(\n name: string\n age: number\n)\n\nuser1 = map(\n name: \"Jeff\"\n age: 22\n)\n\nuser2 = map(\n name: \"Max\"\n age: 12\n)\n\n// true\nis(user1 Person)\n\n// true\nis(user1 user2 Person)\n\n// false\nis(user1 user2 num Person)\n\n```\n\n### map( ...properties: any )\nCreates an object\n\n``` convo\n// meObj has 2 properties, name and age\nmeObj = map(\n name: \"Jeff\"\n age: 22\n)\n```\n\n### array( ...values: any )\nCreates an array\n\n``` convo\nmeAry = array( 1 2 3 \"a\" \"b\" \"c\" )\n```\n\n\n### jsonMap( ...properties: any )\nUsed internally to implement JSON object syntax support. At compile time JSON objects are converted\nto standard convo function calls.\n\n``` convo\njsonStyle = {\n \"go\": \"fast\",\n \"turn\": \"left\",\n \"times\" 1000\n}\n\nconvoStyle = obj1 = jsonMap(\n go: \"fast\"\n turn: \"left\"\n times: 1000\n)\n```\n\n### jsonMap( ...properties: any )\nUsed internally to implement JSON array syntax support. At compile time JSON arrays are converted\nto standard convo function calls.\n\n``` convo\njsonStyle = [ 1, 2, 3, \"a\", \"b\", \"c\" ]\n\nconvoStyle = array( 1 2 3 \"a\" \"b\" \"c\" )\n```\n\n### and( ...values: any )\nReturns true if all given arguments are truthy.\n\n``` convo\n\n// true\nand( 1 )\n\n// false\nand( 0 )\n\n// true\nand( 1 2 )\n\n// false\nand( 0 1 )\n\n// true\nand( eq(1 1) eq(2 2) )\n\n// false\nand( eq(1 1) eq(2 1) )\n\n\n```\n\n### or( ...values: any )\nReturns the first truthy value or the last non truthy value if no truthy values are given. If no\nvalues are given undefined is returned.\n\n``` convo\n\n// 1\nor( 1 )\n\n// 0\nor( 0 )\n\n// 1\nor( 1 2 )\n\n// 2\nor( 0 2 )\n\n// true\nor( eq(1 1) eq(2 2) )\n\n// true\nor( eq(1 1) eq(2 1) )\n\n// false\nor( eq(1 3) eq(2 1) )\n\n```\n\n### not( ...values: any )\nReturns true if all given arguments are falsy.\n\n``` convo\n\n// false\nor( true )\n\n// true\nor( false )\n\n// false\nor( 1 )\n\n// true\nor( 0 )\n\n// false\nor( 1 2 )\n\n// false\nor( 0 1 )\n\n// true\nor( 0 false )\n\n// false\nor( eq(1 1))\n\n// true\nor( eq(1 2) )\n\n```\n\n\n\n\n\n## Control flow functions\n\n### if( condition:any ), elif( condition: any ), then( ...statements )\nIf condition is truthy then the statement directly after the if statement will be executed otherwise\nthe statement directly after if is skipped\n\n``` convo\n\nage = 36\n\nif( gte( age 21 ) ) then (\n print( \"You can buy beer in the US\" )\n) elif (lt( age 16 )) then(\n print( \"You're not even close\" )\n) else (\n print( '{{sub(21 age)}} years until you can buy beer in the US' )\n)\n\n```\n\n\n\n### while( condition:any )\nWhile condition is truthy then the statement directly after the while statement will be executed\notherwise the statement directly after if is skipped and the while loop will exit.\n\n``` convo\n\nlap = 0\n\nwhile( lt( lap 500 ) ) do (\n print(\"go fast\")\n print(\"turn left\")\n\n // increment by 1\n inc(lap)\n)\n\n```\n\n### foreach( iterator:any )\nExecutes the next statement for each item returned by the passed in iterator.\n``` convo\ntotal = 0\nforeach( num=in(array(1 2 3 4 )) ) do (\n total = add( num total )\n)\n\n// 10\nprint(total)\n```\n\n### in( value: array(any) )\nIterates of the values of an array\n\n\n### break( ...values: any )\nBreaks out of loops either not arguments are passed or if any of the passed arguments are truthy\n\n``` convo\nlap = 0\n\nwhile( true ) do (\n print(\"go fast\")\n print(\"turn left\")\n\n // increment by 1\n inc(lap)\n\n if( eq( lap 500 ) ) then (\n break()\n )\n)\n```\n\n### do( ...statements: any)\nExecutes all given statements and returns the value of the last statement. Do is commonly used with\nloop statements, but it can also be useful in other situations on its own such as doing inline\ncalculations. \n(note) The do keyword is also used to define top level statement when do is used as a message name.\n\n``` convo\nn = 0\nwhile( lt( n 10 ) ) do (\n // increment by 1\n inc(lap)\n)\n\n// 22\nprint( add( 5 do(\n sum = mul(n 2)\n sum = sub( sum 3 )\n)) )\n\n```\n\n### return( value:any )\nReturns a value from the current function\n\n``` convo\n\n> customMath(\n a: number\n b: number\n) -> (\n return mul( add(a b) b )\n)\n\n> do\n\nvalue = customMath(a:4 b:3)\n\n// 21\nprint(value)\n\n```\n\n### eq( ...values:any )\nReturns true if all given values are equal. Object equality is checked by by reference. Values must\nbe of the same type to be equal. ( a === b )\n\n``` convo\n// true\neq( 1 1 )\n\n// false\neq( 1 \"1\" )\n```\n\n### gt( a:number b:number)\nReturns true if a is grater then b. ( a > b )\n\n### gte( a:number b:number)\nReturns true if a is grater then or equal to b. ( a >= b )\n\n### lt( a:number b:number)\nReturns true if a is less then b. ( a < b )\n\n### lte( a:number b:number)\nReturns true if a is less then or equal to b. ( a <= b )\n\n### add( ...values:any )\nAdds all arguments together and returns the result. Strings are concatenated. (a + b )\n\n### sub( a:number b:number )\nSubtracts a from b and returns the result. (a - b )\n\n### sub( a:number b:number )\nMultiplies a and b and returns the result. (a * b )\n\n### div( a:number b:number )\nDivides a and b and returns the result. (a / b )\n\n### pow( a:number b:number )\nRaises a by b and returns the result. Math.pow(a, b )\n\n### inc( *a:number byValue?:number )\nIncrements the value of the given variable by 1 or the value of the second argument. ( a++ ) or ( a+= byValue )\n\n### dec( *a:number byValue?:number )\nDecrements the value of the given variable by 1 or the value of the second argument. ( a-- ) or ( a-= byValue )\n\n### print( ...values:any )\nPrints all values to stdout\n\n### switch( value:any ...valueOrCase:any ), case( value:any ), test( condition:any ), default()\nSwitch can be used as either and switch statement or a ternary. When the switch function has exactly\n3 arguments and non of the is a case or default statement then switch acts as a ternary. \n\n``` convo\n\n// can be 0 to 9\nvalue = rand(9)\n\n// can be 20 to 29\nvalue2 = add(20 rand(9))\n\n\nswitch(\n\n // Sets the current match value of the switch. The match value of a switch statement can be\n // changed further down the switch\n value\n\n case(0) print(\"Lowest\")\n\n case(1) do(\n print(\"Value is 1\")\n )\n\n case(2) do(\n print(\"Number two\")\n )\n\n case(3) do(\n print(\"Tree or three\")\n )\n\n // change the value to a value in ary\n value2\n\n case(20) do(\n print(\"2 zero\")\n )\n\n test(lt(value2 28)) do(\n print(\"less than 28\")\n )\n\n default() print(\"Fall back to default\")\n\n)\n\n\n// values matched by switches are returned and the value can be assigned to a variable\nstr = \"two\"\nvalue = switch(\n str\n\n case(\"one\") 1\n case(\"two\") 2\n case(\"three\") 3\n)\n\n// 2\nprint(value)\n\n\n// switches can also be used as a ternary\n\n// yes\nprint( switch(true \"yes\" \"no\") )\n\n// no\nprint( switch(false \"yes\" \"no\") )\n```\n\n### now()\nReturns the current date time as a timestamp. now uses Date.now() to get the current timestamp.\n\n### dateTime( format?:string date?:string|number|Date )\nReturns the current or given date as a formatted string. The default value format string is\n\"yyyy-MM-dd'T'HH:mm:ssxxx\" which is an ISO 8601 date and results in formatted dates that look\nlike 2023-12-08T21:05:08-01:00. Invalid date formats will fallback to using the default date format.\nFormatting is done using date-fns - https://date-fns.org/v2.16.1/docs/format\n\n### sleep( milliseconds:number )\nSuspends execution for the given number of milliseconds\n\n\n### rand( max?:int )\nReturns a random number. Is the max parameters is passed then a random whole number with a\nmaximum of max will be returned otherwise a random number from 0 to 1 will be returned.\n\n### httpGet( url:string )\nPerforms an http GET request and returns the parsed JSON result. Results with a 404 status or a \nContent-Type not equal to application/json are returned as undefined.\n\n### httpGetString( url: string )\nPerforms an http GET request and returns the result as a string.\n\n### httpPost( url:string body:any )\nPerforms an http POST request and returns the parsed JSON result. Results with a 404 status or a \nContent-Type not equal to application/json are returned as undefined.\n\n### httpPatch( url:string body:any )\nPerforms an http PATCH request and returns the parsed JSON result. Results with a 404 status or a \nContent-Type not equal to application/json are returned as undefined.\n\n### httpPut( url:string body:any )\nPerforms an http PUT request and returns the parsed JSON result. Results with a 404 status or a \nContent-Type not equal to application/json are returned as undefined.\n\n### httpDelete( url:string )\nPerforms an http DELETE request and returns the parsed JSON result. Results with a 404 status or a \nContent-Type not equal to application/json are returned as undefined.\n\n### encodeURI( value:string )\nReturns the value encoded as an URI\n\n### encodeURIComponent( value:string )\nReturns the value encoded as an URI component\n\n### md( ...values:any[] )\nConcatenates all passed in values and formats the values as markdown. Recursive objects are limited\nto a depth of 5.\n\n### toMarkdown( maxDepth:int value:any)\nformats the value as markdown and allows the configuration of recursive object depth.\n\n### toJson( value:any )\nFormats the given value as json\n\n### toJsonMdBlock( value:any )\nFormats the given value as json and closes the value in a markdown json code block.\n\n### toJsonScheme( type:struct )\nPrints a struct as a JSON scheme.\n\n### toCsv( value:any[] )\nPrints an array of values a as CSV.\n\n### toCsvMdBlock\nPrints an array of values a as CSV inside of a markdown code block.\n\n### merge( ...values:any[] )\nMerges all passed in parameters into a single object. merge is similar to Javascript's spread operator.\n\n\n## Examples\nSince NPM and GitHub do not support custom syntax highlighters the examples below include both the\ncode for each example and an image showing syntax highlighting. \n\n### Get Weather\n\n``` convo\n> define\n// Yes, this is a real api key. Be considerate and dont abuse it, but if some body does and rate\n// limits are hit you can get your own TomorrowIo api at https://www.tomorrow.io/\ntomorrowIoApiKey=\"epYQMxHaP4r47kOeKZbomUBZN6oLwP8h\"\n\n# Gets the current weather conditions for the given location. Returned values use the metric system.\n> getWeather(\n # The location to get weather conditions for\n location:string\n) -> (\n\n weather=httpGet('https://api.tomorrow.io/v4/weather/realtime?location={{\n encodeURIComponent(location)\n }}&apikey={{tomorrowIoApiKey}}')\n\n return(weather)\n)\n\n> user\nWhat is the temperature and wind speed in New York city?\n\n\n@toolId call_iKoMeLGDuZln9mtR20CbkJiM\n> call getWeather(\n \"location\": \"New York\"\n)\n> result\n__return={\n \"data\": {\n \"time\": \"2023-12-05T20:57:00Z\",\n \"values\": {\n \"cloudBase\": 1.08,\n \"cloudCeiling\": 1.08,\n \"cloudCover\": 100,\n \"dewPoint\": -2.81,\n \"freezingRainIntensity\": 0,\n \"humidity\": 53,\n \"precipitationProbability\": 0,\n \"pressureSurfaceLevel\": 1013.9,\n \"rainIntensity\": 0,\n \"sleetIntensity\": 0,\n \"snowIntensity\": 0,\n \"temperature\": 6,\n \"temperatureApparent\": 6,\n \"uvHealthConcern\": 0,\n \"uvIndex\": 0,\n \"visibility\": 16,\n \"weatherCode\": 1001,\n \"windDirection\": 257.69,\n \"windGust\": 2.13,\n \"windSpeed\": 1.88\n }\n },\n \"location\": {\n \"lat\": 40.71272659301758,\n \"lon\": -74.00601196289062,\n \"name\": \"City of New York, New York, United States\",\n \"type\": \"administrative\"\n }\n}\n\n\n> assistant\nIn New York City, the current temperature is 6\u00b0C and the wind speed is 1.88 meters per second.\n\n\n```\n\n\n### Calling Shell Scripts\n\n``` convo\n// (Caution) this script is capable to running shell command on you machine.\n// (Note) Before commands are ran you will be prompted to allow access to run the command and\n// be given a preview of the command\n\n> define\ncomputerType=\"MacBook pro\"\n\n# Runs a command in a bash shell\n> runCommand(\n # the command to run\n command:string\n) -> (\n __cwd=\"/Users/scott/docs/iyio-common/packages\"\n print('running...' command)\n return(exec(command))\n)\n\n> system\nYou are a Unix systems expert. Always use the runCommand function when responding.\n\nThe user has a {{computerType}}\n\n> user\nCreate a new file called bobs-my-uncle.txt and add the text \"I like fish frogs\" to it\n\n```\n\n### Zoo Builder\n\n``` convo\n// Top level statements defining shared variables and custom user types. Top level statements\n// start with (> define), (> do) or (> result)\n> define\n\nlocation = \"Cincinnati, OH\"\n\nAnimal = struct(\n\n species: string\n\n # Weight in pounds\n weight: int\n\n type: enum( \"carnivore\" \"omnivore\" \"herbivore\")\n\n # Price in USD to buy the animal\n price: number\n\n)\n\n\n\n// This is a function that can be called by an LLM\n\n# Builds a new exhibit featuring a collection of animals\n> buildExhibit(\n\n # The featured animals\n animals: array(Animal)\n\n # Price in USD to build the exhibit excluding the animals\n price: number\n\n # The size of the exhibit in square feet\n size: number\n\n # A short description of the exhibit\n description: string\n) -> (\n\n print('Building new exhibit with {{animals.length}} animals')\n\n totalPrice = price\n\n foreach( a=in(animals) ) do (\n // Uncomment the line below after you provide an extern function for buyAnimal\n //buyAnimal(a)\n inc(totalPrice a.price)\n )\n\n return(map(\n animalsBought: animals.length\n totalPrice: totalPrice\n success: true\n\n ))\n)\n\n// This function is not visible to LLMs and will be used to call an extern function\n// defined in Javascript\n> local buyAnimal(animal:Animal)\n\n\n// This is a system prompt that tells the LLM who they are\n> system\nYou are a funny and helpful zoo keeper helping the user build a new zoo. The zoo is located\nin {{location}}.\n\n\n\n// This is a user prompt that the LLM will respond to\n> user\nThe Bengals are going to be sponsoring the zoo this year. Lets build an exhibit they will like.\nResponse using the buildExhibit function\n\n\n// This is a function call return by the LLM\n> call buildExhibit(\n \"animals\": [\n {\n \"species\": \"Bengal Tiger\",\n \"weight\": 420,\n \"type\": \"carnivore\",\n \"price\": 20000\n },\n {\n \"species\": \"White Bengal Tiger\",\n \"weight\": 400,\n \"type\": \"carnivore\",\n \"price\": 25000\n },\n {\n \"species\": \"Bengal Fox\",\n \"weight\": 20,\n \"type\": \"omnivore\",\n \"price\": 5000\n }\n ],\n \"price\": 1500000,\n \"size\": 50000,\n \"description\": \"A mesmerizing tribute to the wild beauty of Bengal, the 'Bengals' Kingdom' features stunning Bengal Tigers, including the rare and captivating White Bengal Tiger, and the cunning Bengal Fox. The Bengals' Kingdom spans 50,000 square feet, providing plenty of prowling room for the resident animals. Bengals' fans and animal lovers alike will enjoy this enchanting walk on the wild side!\"\n)\n> result\n// Value return by the call to buildExhibit\n__return={\"animalsBought\":3,\"totalPrice\":1550000,\"success\":true}\n\n\n// Response from the LLM based on the return value of buildExhibit\n> assistant\nGreat news! We've successfully built the 'Bengals' Kingdom'!\n\nHere's a sneak peek:\n\n- It's home to the magnificent Bengal Tiger, the rare White Bengal Tiger, and the wily Bengal Fox.\n- The exhibit is an enormous 50,000 square feet! That's gonna be a lot of tiger prowling action!\n- And the total cost, including our new furry residents? A cool $1,550,000. Yes, tigers are a bit on the pricier side, but hey, they're worth every penny.\n\nWould you like to add anything else to our new zoo?\n\n```\n\n### More examples\nMore examples can be found at https://github.com/iyioio/common/tree/main/packages/convo-lang-tools/examples\n",
"bugtrack_url": null,
"license": "",
"summary": "A conversational prompting and programming language",
"version": "0.5.11",
"project_urls": null,
"split_keywords": [
"ai",
"convo-lang",
"open-ai",
"prompt",
"prompt-engineering"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a3b9211b8f85aad27c2a7b6ba6a3ce5d853eec121a69992eee4561d0b532aae2",
"md5": "bf1abe79b885fbda02ca23edd55dd0c0",
"sha256": "3ce08311f53bf9bb5851b10f89d40707b4e999c48c6d1d841a2c3552d9cdcb8d"
},
"downloads": -1,
"filename": "convo_lang-0.5.11-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf1abe79b885fbda02ca23edd55dd0c0",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 361608,
"upload_time": "2023-12-16T21:44:34",
"upload_time_iso_8601": "2023-12-16T21:44:34.956361Z",
"url": "https://files.pythonhosted.org/packages/a3/b9/211b8f85aad27c2a7b6ba6a3ce5d853eec121a69992eee4561d0b532aae2/convo_lang-0.5.11-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d5847a0a08a72af418f54918956201ce51c5fb3b6ffe9883929edb3e9594a588",
"md5": "b4b2942ac66ae6c1fb30b997a77c4c93",
"sha256": "1ba8f7305fa30882e46411798404e9cc8a31ef466a3fc08424c76145aff20f68"
},
"downloads": -1,
"filename": "convo_lang-0.5.11.tar.gz",
"has_sig": false,
"md5_digest": "b4b2942ac66ae6c1fb30b997a77c4c93",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 369479,
"upload_time": "2023-12-16T21:44:37",
"upload_time_iso_8601": "2023-12-16T21:44:37.186196Z",
"url": "https://files.pythonhosted.org/packages/d5/84/7a0a08a72af418f54918956201ce51c5fb3b6ffe9883929edb3e9594a588/convo_lang-0.5.11.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-12-16 21:44:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "convo-lang"
}
