class kork.ast.ExternFunctionDef(name: str, params: kork.ast.ParamList, return_type: str, implementation: Optional[Callable] = None, doc_string: str = '')[source]#

Bases: kork.ast.Stmt

External function definition.

add_implementation(implementation: Callable) → kork.ast.ExternFunctionDef[source]#: Add an implementation to an external function definition.

doc_string: str = ''#

implementation: Optional[Callable] = None#

name: str#

params: kork.ast.ParamList#

return_type: str#

class kork.ast.FunctionCall(name: str, args: Sequence[kork.ast.Expr])[source]#

Bases: kork.ast.Expr

Represent a function call.

args: Sequence[kork.ast.Expr]#

name: str#

class kork.ast.FunctionDef(name: str, params: kork.ast.ParamList, body: Sequence[Union[kork.ast.Stmt, kork.ast.Expr]], return_type: str)[source]#

Bases: kork.ast.Stmt

Represent a function definition with an implementation.

body: Sequence[Union[kork.ast.Stmt, kork.ast.Expr]]#

name: str#

params: kork.ast.ParamList#

return_type: str#

class kork.ast.Grouping(expr: kork.ast.Expr)[source]#

Bases: kork.ast.Expr

A grouping expression.

expr: kork.ast.Expr#

class kork.ast.List_(elements: Sequence[kork.ast.Expr])[source]#

Bases: kork.ast.Expr

List literal.

elements: Sequence[kork.ast.Expr]#

class kork.ast.Literal(value: Union[float, int, bool, None, str])[source]#

Bases: kork.ast.Expr

A literal expression.

value: Union[float, int, bool, None, str]#

class kork.ast.Param(name: str, type_: str)[source]#

Bases: kork.ast.Stmt

Represent a function parameter.

name: str#

type_: str#

class kork.ast.ParamList(params: Sequence[kork.ast.Param])[source]#

Bases: kork.ast.Stmt

Represent a list of function parameters.

params: Sequence[kork.ast.Param]#

class kork.ast.Program(stmts: Sequence[Union[kork.ast.Stmt, kork.ast.Expr]])[source]#

Bases: kork.ast.Stmt

Represent a program.

stmts: Sequence[Union[kork.ast.Stmt, kork.ast.Expr]]#

class kork.ast.Stmt[source]#

Bases: abc.ABC

Abstract statement.

accept(visitor: kork.ast.Visitor, **kwargs: Any) → Any[source]#: Accept implementation for a visitor.

class kork.ast.Unary(operator: str, right: kork.ast.Expr)[source]#

Bases: kork.ast.Expr

A unary expression.

operator: str#

right: kork.ast.Expr#

class kork.ast.VarDecl(name: str, value: kork.ast.Expr)[source]#

Bases: kork.ast.Stmt

Represent a variable declaration.

name: str#

value: kork.ast.Expr#

class kork.ast.Variable(name: str)[source]#

Bases: kork.ast.Expr

Variable reference.

name: str#

class kork.ast.Visitor[source]#

Bases: abc.ABC

Abstract visitor interface.

kork.ast_printer module#

class kork.ast_printer.AbstractAstPrinter[source]#

Bases: kork.ast.Visitor, abc.ABC

abstract visit(element: Union[kork.ast.Stmt, kork.ast.Expr], pretty_print: bool = False) → str[source]#: Entry-point for printing the AST.

class kork.ast_printer.AstPrinter[source]#

Bases: kork.ast_printer.AbstractAstPrinter

Default AST Printer implementation.

visit(element: Union[kork.ast.Stmt, kork.ast.Expr], pretty_print: bool = False) → str[source]#: Entry-point for printing the AST.

visit_assign(assign: kork.ast.Assign, **data: Any) → str[source]#: Print an assignment.

visit_binary(binary: kork.ast.Binary, **data: Any) → str[source]#: Print a binary expression.

visit_extern_function_def(extern_function_def: kork.ast.ExternFunctionDef, **data: Any) → str[source]#: Print an extern function definition.

visit_function_call(call: kork.ast.FunctionCall, **data: Any) → str[source]#: Print a function call.

visit_function_def(function_def: kork.ast.FunctionDef, **data: Any) → str[source]#: Print a function definition.

visit_grouping(grouping: kork.ast.Grouping, **data: Any) → str[source]#

visit_list_(list_: kork.ast.List_, **data: Any) → str[source]#: Print a list.

visit_literal(literal: kork.ast.Literal, **data: Any) → str[source]#: Print a literal.

visit_param(param: kork.ast.Param, **data: Any) → str[source]#: Print a parameter.

visit_param_list(param_list: kork.ast.ParamList, **data: Any) → str[source]#: Print a parameter list.

visit_program(program: kork.ast.Program, **data: Any) → str[source]#: Print a program.

visit_unary(unary: kork.ast.Unary, **data: Any) → str[source]#: Visit a unary expression.

visit_var_decl(var_decl: kork.ast.VarDecl, **data: Any) → str[source]#: Print a variable declaration.

visit_variable(variable: kork.ast.Variable, **data: Any) → str[source]#: Print a variable.

kork.chain module#

Implementation of a programming chain.

class kork.chain.CodeChain(*, memory: Optional[langchain.schema.BaseMemory] = None, callback_manager: langchain.callbacks.base.BaseCallbackManager = None, verbose: bool = None, llm: langchain.schema.BaseLanguageModel, interpreter: Callable[[str, kork.environment.Environment], kork.interpreter.InterpreterResult], ast_printer: kork.ast_printer.AbstractAstPrinter, context_retriever: Optional[kork.retrieval.AbstractContextRetriever] = None, example_retriever: Optional[kork.examples.AbstractExampleRetriever] = None, instruction_template: langchain.prompts.prompt.PromptTemplate = PromptTemplate(input_variables=['language_name', 'external_functions_block'], output_parser=None, partial_variables={}, template='You are programming in a language called "{language_name}".\n\nYou are an expert programmer and must follow the instructions below exactly.\n\nYour goal is to translate a user query into a corresponding and valid {language_name}\nprogram.\n\n{external_functions_block}\n\nDo not assume that any other functions except for the ones listed above exist.\n\nWrap the program in <code> and </code> tags.\n\nStore the solution to the query in a variable called "result".\n\nHere is a sample valid program:\n\n<code>\nvar x = 1 # Assign 1 to the variable x\nvar result = 1 + 2 # Calculate the sum of 1 + 2 and assign to result\nvar result = x # Assign the value of x to result\n</code>\n\nGuidelines:\n- Do not use operators, instead invoke appropriate external functions.\n- Do not declare functions, do not use loops, do not use conditionals.\n- Solve the problem only using variable declarations and function invocations.\n\nBegin!\n', template_format='f-string', validate_template=True), input_key: str = 'query', language_name: str = '😼', input_formatter: Union[Literal['text_prefix'], Literal['triple_quotes'], Literal['markdown_text'], None, Callable[[str], str]] = 'triple_quotes', **extra_data: Any)[source]#

Bases: langchain.chains.base.Chain

A coding chain.

class Config[source]#

Bases: object

Configuration for this pydantic object.

arbitrary_types_allowed = True#

extra = 'allow'#

ast_printer: AbstractAstPrinter#: The AST printer to use for the coding chain.

context_retriever: Optional[AbstractContextRetriever]#

Context to inject into the environment and prompt.

At the moment, this context is limited to external functions.

example_retriever: Optional[AbstractExampleRetriever]#: Examples that should be added to the prompt.

classmethod from_defaults(*, llm: langchain.schema.BaseLanguageModel, interpreter: typing.Callable[[str, kork.environment.Environment], kork.interpreter.InterpreterResult] = <function run_interpreter>, ast_printer: kork.ast_printer.AbstractAstPrinter = <kork.ast_printer.AstPrinter object>, context: typing.Optional[typing.Union[kork.retrieval.AbstractContextRetriever, typing.Sequence[typing.Union[kork.ast.ExternFunctionDef, typing.Callable]]]] = None, examples: typing.Optional[typing.Union[kork.examples.AbstractExampleRetriever, typing.Sequence[typing.Tuple[str, kork.ast.Program]]]] = None, instruction_template: langchain.prompts.prompt.PromptTemplate = PromptTemplate(input_variables=['language_name', 'external_functions_block'], output_parser=None, partial_variables={}, template='You are programming in a language called "{language_name}".\n\nYou are an expert programmer and must follow the instructions below exactly.\n\nYour goal is to translate a user query into a corresponding and valid {language_name}\nprogram.\n\n{external_functions_block}\n\nDo not assume that any other functions except for the ones listed above exist.\n\nWrap the program in <code> and </code> tags.\n\nStore the solution to the query in a variable called "result".\n\nHere is a sample valid program:\n\n<code>\nvar x = 1 # Assign 1 to the variable x\nvar result = 1 + 2 # Calculate the sum of 1 + 2 and assign to result\nvar result = x # Assign the value of x to result\n</code>\n\nGuidelines:\n- Do not use operators, instead invoke appropriate external functions.\n- Do not declare functions, do not use loops, do not use conditionals.\n- Solve the problem only using variable declarations and function invocations.\n\nBegin!\n', template_format='f-string', validate_template=True), input_key: str = 'query', language_name: str = '😼', input_formatter: typing.Union[typing.Literal['text_prefix'], typing.Literal['triple_quotes'], typing.Literal['markdown_text'], None, typing.Callable[[str], str]] = 'markdown_text') → kork.chain.CodeChain[source]#

Create a code chain from pre-configured defaults.

Parameters

llm – The language model to use for coding
interpreter – The interpreter that will be used to execute the program
ast_printer – An ast printer that can print the AST as a text string
context – Either a list of functions or a context retriever. The list of functions can be a mixture of python callables and Kork external functions. All python functions will be converted into Kork external functions, and everything passed into the default context retriever.
examples – An example retriever or a list of examples. If a list of examples, a simple example retriever will be created.
instruction_template – Use to customize the instruction components of the prompt.
language_name – The language name to use for the prompt.
input_formatter – A formatting that will be applied to the input part of each example tuple, if passing in a list of examples.
input_key – The input key to use.

Returns

A code chain

input_formatter: InputFormatter#: The smirking kat programming language; aka Kork; aka 😼

input_key: str#

instruction_template: PromptTemplate#: Template for the instruction prompt.

interpreter: Callable[[str, Environment], InterpreterResult]#: The interpreter to use for the coding chain.

language_name: str#

llm: BaseLanguageModel#: The language model to use for the coding chain.

prepare_context(query: str, variables: Optional[Mapping[str, Any]] = None) → Tuple[kork.environment.Environment, kork.prompt_adapter.FewShotTemplate][source]#

Get the pre-populated environment and the few shot template.

Parameters

query – The query to prepare the context for.
variables – Any variables that should be added to the context.

Returns

The prepopulated environment and a pre-formatted few shot template.

class kork.chain.CodeResult[source]#

Bases: TypedDict

Result of a code chain.

code: str#

environment: Optional[kork.environment.Environment]#

errors: Sequence[Exception]#

raw: str#

kork.display module#

Utils for displaying chain results in a notebook.

class kork.display.HtmlResult[source]#

Bases: TypedDict

A result that can be displayed in a notebook.

code: str#

correct: str#

errors: str#

expected: str#

query: str#

raw: str#

result: str#

kork.display.as_html_dict(code_result: kork.chain.CodeResult, query: Optional[str] = None, expected_answer: Optional[Any] = None, result_key: str = 'result', pretty_print: bool = True) → kork.display.HtmlResult[source]#: Use to generate a dict that can be easily displayed in an IPython notebook.

kork.display.as_img_tag(image: None) → str[source]#: Get an HTML representation of an image.

kork.display.display_code_result(code_result: kork.chain.CodeResult, query: typing.Optional[str] = None, expected_answer: typing.Optional[typing.Any] = <kork.display._NoExpectedAnswer object>, columns: typing.Optional[typing.Sequence[str]] = None, result_key: str = 'result') → Any[source]#: Display a code result as a table.

kork.display.display_html_results(html_results: Union[Sequence[kork.display.HtmlResult], kork.display.HtmlResult], columns: Optional[Sequence[str]] = None) → Any[source]#: Display a sequence of HTML results as a table.

kork.display.image_base64(image: None) → str[source]#: Get a base64 representation of an image.

kork.environment module#

class kork.environment.Environment(parent: typing.Optional[kork.environment.Environment] = None, variables: typing.Dict[str, typing.Any] = <factory>)[source]#

Bases: object

Environment for storing variables and function definitions.

clone() → kork.environment.Environment[source]#

Clone a root level environment, with deep copy on variables.

Cloning functionality is provided because the environment is a mutable variable.

Biggest danger is mutating the variables dict which the caller may retain a reference to.

TODO(Eugene): Refactor to make this less dangerous.

get_symbol(name: str) → Any[source]#

Get a symbol from the environment.

Parameters: name – symbol name to lookup
Returns: SymbolValue for the given symbol if it exists, otherwise raises an error

list_external_functions() → List[kork.ast.ExternFunctionDef][source]#: Get a list of the externally defined foreign functions.

parent: Optional[kork.environment.Environment] = None#

set_symbol(name: str, value: Any) → Any[source]#: Set a symbol in the environment.

variables: Dict[str, Any]#

kork.environment.create_environment(extern_function_defs: Sequence[kork.ast.ExternFunctionDef], external_variables: Optional[Mapping[str, Any]] = None) → kork.environment.Environment[source]#: Create a new environment with pre-populated state.

kork.examples module#

Interface to specify kork examples easily.

class kork.examples.AbstractExampleRetriever[source]#

Bases: abc.ABC

Abstract interface for an example retriever.

An example interface must implement the retrieve method which returns a list of relevant examples based on the given query.

abstract retrieve(query: str) → List[Tuple[str, str]][source]#: Retrieve examples.

class kork.examples.SimpleExampleRetriever(examples: Sequence[Tuple[str, str]])[source]#

Bases: kork.examples.AbstractExampleRetriever

Simple example retriever.

Simple example that returns the examples it was initialized with.

Supports initialization from a list of programs.

Example:

from kork import SimpleExampleRetriever, AstPrinter, c_, r_

simple_example_retriever = SimpleExampleRetriever.from_programs(
    language_name="kork",
    examples=[
        ("add 1 2", r_(c_(add, 1, 2))),
        ("add 1 2 3", r_(c_(add, 1, 2, 3))),
        ],
    ast_printer=AstPrinter(),
)

examples = simple_example_retriever.retrieve("add 1 2")

classmethod from_programs(language_name: str, examples: Sequence[Tuple[str, kork.ast.Program]], ast_printer: kork.ast_printer.AbstractAstPrinter) → kork.examples.SimpleExampleRetriever[source]#

Create a simple example retriever from programs.

Parameters

language_name – The language name to use for the markdown code blocks.
examples – A sequence of tuples of the form (query, desired program).
ast_printer – The ast printer to use to format the desired output.

Returns

A simple example retriever.

retrieve(query: str) → List[Tuple[str, str]][source]#: Retrieve examples that best match the given query.

kork.examples.c_(name: Callable, *args: Any) → kork.ast.FunctionCall[source]#: Create a kork function call.

kork.examples.format_examples(language_name: str, examples: Sequence[Tuple[str, kork.ast.Program]], ast_printer: kork.ast_printer.AbstractAstPrinter, input_formatter: Union[Literal['text_prefix'], Literal['triple_quotes'], Literal['markdown_text'], None, Callable[[str], str]] = None) → List[Tuple[str, str]][source]#: Format examples.

kork.examples.format_text(text: str, input_formatter: Union[Literal['text_prefix'], Literal['triple_quotes'], Literal['markdown_text'], None, Callable[[str], str]] = None) → str[source]#

An encoder for the input text.

Parameters

text – the text to encode
input_formatter – the formatter to use for the input * None: use for single sentences or single paragraphs, no formatting * triple_quotes: surround input with “””, use for long text * text_prefix: same as triple_quote but with `TEXT: ` prefix * Callable: user provided function

Returns

The encoded text if it was encoded

kork.examples.r_(expr: kork.ast.Expr) → kork.ast.Program[source]#: Assign last program expression to a result variable.

kork.exceptions module#

Definitions for custom Kork exceptions.

exception kork.exceptions.KorkException[source]#

Bases: Exception

Generic Kork exception.

exception kork.exceptions.KorkInterpreterException[source]#

Bases: kork.exceptions.KorkException

Exceptions raised during interpretation.

exception kork.exceptions.KorkRunTimeException[source]#

Bases: kork.exceptions.KorkInterpreterException

An exception that is raised during Kork interpreter runtime.

exception kork.exceptions.KorkSyntaxException[source]#

Bases: kork.exceptions.KorkException

Exceptions raised during syntax parsing.

exception kork.exceptions.LLMParseException[source]#

Bases: kork.exceptions.KorkException

Failed to parse LLM output.

kork.foreign_funcs module#

API to import foreign functions.

class kork.foreign_funcs.FunctionInfo[source]#

Bases: TypedDict

Information about a function.

args: List[Tuple[str, Any, Any]]#

docstring: str#

name: str#

return_type: Any#

kork.foreign_funcs.to_extern_func_def(func: Callable) → kork.ast.ExternFunctionDef[source]#: Convert a python function to a kork external function definition.

kork.foreign_funcs.to_kork_function_call(func: Callable, *args: Any) → kork.ast.FunctionCall[source]#: Convert a python function call to a kork function call.

kork.interpreter module#

class kork.interpreter.Interpreter(program: kork.ast.Program, environment: kork.environment.Environment)[source]#

Bases: kork.ast.Visitor

Kork’s default interpreter.

intepret() → None[source]#: Interpret the program.

visit_assign(assign: kork.ast.Assign) → None[source]#: Visit an assignment.

visit_binary(binary: kork.ast.Binary) → Any[source]#: Visit a binary expression.

visit_extern_function_def(extern_function_def: kork.ast.ExternFunctionDef) → None[source]#: Visit an external function definition.

visit_function_call(call: kork.ast.FunctionCall) → Any[source]#: Visit a function call.

visit_function_def(function_def: kork.ast.FunctionDef) → None[source]#: Visit a function definition.

visit_grouping(grouping: kork.ast.Grouping) → Any[source]#: Visit a grouping.

visit_list_(list_: kork.ast.List_) → list[source]#: Visit a list.

visit_literal(literal: kork.ast.Literal) → Optional[Union[int, float, bool, str]][source]#: Visit a number.

visit_program(program: kork.ast.Program) → None[source]#: Visit a program.

visit_unary(unary: kork.ast.Unary) → Any[source]#: Visit a unary expression.

visit_var_decl(var_decl: kork.ast.VarDecl) → None[source]#: Visit a variable declaration.

visit_variable(variable: kork.ast.Variable) → Any[source]#: Visit a variable.

class kork.interpreter.InterpreterResult[source]#

Bases: TypedDict

Use this to return the result of the interpreter.

environment: kork.environment.Environment#

errors: Sequence[Exception]#

kork.interpreter.run_interpreter(code: str, environment: Optional[kork.environment.Environment] = None) → kork.interpreter.InterpreterResult[source]#

Run the interpreter with the given code.

Parameters

code – The code to run
environment – The environment to run the code in

Returns

the final environment after running the code (this will likely change)

kork.parser module#

Kork’s default AST parser.

Kork uses Lark to parse the AST. The grammar follows closely the one used in Crafting Interpreters for the Lox Programming Language.

https://craftinginterpreters.com/appendix-i.html#expressions

The grammar and parser were clobbered together in a few hours of work.

If you deeply care about language design, please forgive any transgressions, and feel free to help improve the grammar/parser/interpreter.

class kork.parser.AstParser(visit_tokens: bool = True)[source]#

Bases: lark.visitors.Transformer

An ast parser for the given language.

args(*items)[source]#: Create an argument list for a function from the given items.

binary(left, operator, right) → kork.ast.Binary[source]#: Create a binary from the given left, operator and right.

block(*statements)[source]#: Create a block from the given statements.

expr(item) → kork.ast.Expr[source]#: Create an expression from the given item.

extern_function_decl(name, params, return_type) → kork.ast.ExternFunctionDef[source]#: Extern function declaration from the given name, params and return type.

false() → kork.ast.Literal[source]#: Create a false literal.

function_call(name, args) → kork.ast.FunctionCall[source]#: Create a function call from the given name and args.

function_decl(name, params, return_type, block) → kork.ast.FunctionDef[source]#: Function declaration from the given name, params, return type and block.

group(expr) → kork.ast.Grouping[source]#: Create a group from the given expression.

identifier(name) → kork.ast.Variable[source]#: Create a variable reference from the given name.

list(items) → kork.ast.List_[source]#: Create a list literal from the given items.

null() → kork.ast.Literal[source]#: Create a null literal.

number(item) → kork.ast.Literal[source]#

param(name, type_) → kork.ast.Param[source]#: Create a param from the given name and type.

params(*items) → kork.ast.ParamList[source]#: Create a param list from the given items.

program(*items) → kork.ast.Program[source]#: Create a program from the given statements.

scientific(coefficient, exponent) → kork.ast.Literal[source]#

statement(item) → kork.ast.Stmt[source]#: Create a statement from the given item.

string(item) → kork.ast.Literal[source]#

true() → kork.ast.Literal[source]#: Create a true literal.

type(name)[source]#: Create a type from the given name.

unary_r(operator, right) → kork.ast.Unary[source]#: Create a unary from the given operator and left.

var_decl(name, value) → kork.ast.VarDecl[source]#: Variable declaration from the given name and value.

variable_assign(name, value) → kork.ast.Assign[source]#: Create a variable assignment from the given name and value.

kork.parser.parse(source: str) → kork.ast.Program[source]#: Parse the given source code into an AST.

kork.prompt_adapter module#

A prompt adapter to allow working with both regular LLMs and Chat LLMs.

The prompt adapter supports breaking the prompt into:

Instruction Section
(Optional) Example Section

class kork.prompt_adapter.FewShotPromptValue(*, string: Callable[[], str], messages: Callable[[], List[langchain.schema.BaseMessage]])[source]#

Bases: langchain.schema.PromptValue

Integration with langchain prompt format.

class Config[source]#

Bases: object

Configuration for this pydantic object.

arbitrary_types_allowed = True#

extra = 'forbid'#

messages: Callable[[], List[langchain.schema.BaseMessage]]#

string: Callable[[], str]#

to_messages() → List[langchain.schema.BaseMessage][source]#: Get materialized messages.

to_string() → str[source]#: Format the prompt to a string.

class kork.prompt_adapter.FewShotTemplate(*, input_variables: List[str], output_parser: Optional[langchain.schema.BaseOutputParser] = None, partial_variables: Mapping[str, Union[str, Callable[[], str]]] = None, instruction_template: langchain.prompts.prompt.PromptTemplate, examples: Sequence[Tuple[str, str]] = ())[source]#

Bases: langchain.prompts.base.BasePromptTemplate

Code prompt template.

examples: Sequence[Tuple[str, str]]#

format(**kwargs: Any) → str[source]#: Deprecated format method.

format_prompt(**kwargs: Any) → langchain.schema.PromptValue[source]#: Format the prompt.

instruction_template: langchain.prompts.prompt.PromptTemplate#

to_messages(query: str) → List[langchain.schema.BaseMessage][source]#: Get materialized messages.

to_string(query: str) → str[source]#: Format the prompt to a string.

kork.retrieval module#

Logic that attempts to surface the most relevant information for writing code.

class kork.retrieval.AbstractContextRetriever[source]#

Bases: abc.ABC

Abstract interface for retrieving programming context.

abstract retrieve(query: str) → Sequence[kork.ast.ExternFunctionDef][source]#: Retrieve the external function definitions.

class kork.retrieval.SimpleContextRetriever(external_functions: Sequence[kork.ast.ExternFunctionDef] = ())[source]#

Bases: kork.retrieval.AbstractContextRetriever

Retrieve information as was provided without any filtering or re-ranking.

external_functions: Sequence[kork.ast.ExternFunctionDef] = ()#

classmethod from_functions(mixed_funcs: Sequence[Union[kork.ast.ExternFunctionDef, Callable]]) → kork.retrieval.SimpleContextRetriever[source]#

Create a simple retrieval from a sequence of functions.

Parameters: mixed_funcs – A sequence of functions or external function definitions.
Returns: A simple retriever.

retrieve(query: str) → Sequence[kork.ast.ExternFunctionDef][source]#: Retrieve the external function definitions.

kork.utils module#

kork.utils.unwrap_code(language_name: str, text: str) → Optional[str][source]#: Extract code located inside a code tag.

kork.utils.unwrap_tag(tag_name: str, text: str) → Optional[str][source]#: Extract content located inside a tag.

kork.utils.wrap_in_tag(tag_name: str, content: str) → str[source]#: Wrap the content in an HTML style tag.

kork.version module#

Get the version of the package.

Module contents#

class kork.AbstractContextRetriever[source]#

Bases: abc.ABC

Abstract interface for retrieving programming context.

abstract retrieve(query: str) → Sequence[kork.ast.ExternFunctionDef][source]#: Retrieve the external function definitions.

class kork.AbstractExampleRetriever[source]#

Bases: abc.ABC

Abstract interface for an example retriever.

An example interface must implement the retrieve method which returns a list of relevant examples based on the given query.

abstract retrieve(query: str) → List[Tuple[str, str]][source]#: Retrieve examples.

class kork.AstPrinter[source]#

Bases: kork.ast_printer.AbstractAstPrinter

Default AST Printer implementation.

visit(element: Union[kork.ast.Stmt, kork.ast.Expr], pretty_print: bool = False) → str[source]#: Entry-point for printing the AST.

visit_assign(assign: kork.ast.Assign, **data: Any) → str[source]#: Print an assignment.

visit_binary(binary: kork.ast.Binary, **data: Any) → str[source]#: Print a binary expression.

visit_extern_function_def(extern_function_def: kork.ast.ExternFunctionDef, **data: Any) → str[source]#: Print an extern function definition.

visit_function_call(call: kork.ast.FunctionCall, **data: Any) → str[source]#: Print a function call.

visit_function_def(function_def: kork.ast.FunctionDef, **data: Any) → str[source]#: Print a function definition.

visit_grouping(grouping: kork.ast.Grouping, **data: Any) → str[source]#

visit_list_(list_: kork.ast.List_, **data: Any) → str[source]#: Print a list.

visit_literal(literal: kork.ast.Literal, **data: Any) → str[source]#: Print a literal.

visit_param(param: kork.ast.Param, **data: Any) → str[source]#: Print a parameter.

visit_param_list(param_list: kork.ast.ParamList, **data: Any) → str[source]#: Print a parameter list.

visit_program(program: kork.ast.Program, **data: Any) → str[source]#: Print a program.

visit_unary(unary: kork.ast.Unary, **data: Any) → str[source]#: Visit a unary expression.

visit_var_decl(var_decl: kork.ast.VarDecl, **data: Any) → str[source]#: Print a variable declaration.

visit_variable(variable: kork.ast.Variable, **data: Any) → str[source]#: Print a variable.

class kork.CodeChain(*, memory: Optional[langchain.schema.BaseMemory] = None, callback_manager: langchain.callbacks.base.BaseCallbackManager = None, verbose: bool = None, llm: langchain.schema.BaseLanguageModel, interpreter: Callable[[str, kork.environment.Environment], kork.interpreter.InterpreterResult], ast_printer: kork.ast_printer.AbstractAstPrinter, context_retriever: Optional[kork.retrieval.AbstractContextRetriever] = None, example_retriever: Optional[kork.examples.AbstractExampleRetriever] = None, instruction_template: langchain.prompts.prompt.PromptTemplate = PromptTemplate(input_variables=['language_name', 'external_functions_block'], output_parser=None, partial_variables={}, template='You are programming in a language called "{language_name}".\n\nYou are an expert programmer and must follow the instructions below exactly.\n\nYour goal is to translate a user query into a corresponding and valid {language_name}\nprogram.\n\n{external_functions_block}\n\nDo not assume that any other functions except for the ones listed above exist.\n\nWrap the program in <code> and </code> tags.\n\nStore the solution to the query in a variable called "result".\n\nHere is a sample valid program:\n\n<code>\nvar x = 1 # Assign 1 to the variable x\nvar result = 1 + 2 # Calculate the sum of 1 + 2 and assign to result\nvar result = x # Assign the value of x to result\n</code>\n\nGuidelines:\n- Do not use operators, instead invoke appropriate external functions.\n- Do not declare functions, do not use loops, do not use conditionals.\n- Solve the problem only using variable declarations and function invocations.\n\nBegin!\n', template_format='f-string', validate_template=True), input_key: str = 'query', language_name: str = '😼', input_formatter: Union[Literal['text_prefix'], Literal['triple_quotes'], Literal['markdown_text'], None, Callable[[str], str]] = 'triple_quotes', **extra_data: Any)[source]#

Bases: langchain.chains.base.Chain

A coding chain.

class Config[source]#

Bases: object

Configuration for this pydantic object.

arbitrary_types_allowed = True#

extra = 'allow'#

ast_printer: AbstractAstPrinter#: The AST printer to use for the coding chain.

callback_manager: BaseCallbackManager#

context_retriever: Optional[AbstractContextRetriever]#

Context to inject into the environment and prompt.

At the moment, this context is limited to external functions.

example_retriever: Optional[AbstractExampleRetriever]#: Examples that should be added to the prompt.

Create a code chain from pre-configured defaults.

Parameters

llm – The language model to use for coding
interpreter – The interpreter that will be used to execute the program
ast_printer – An ast printer that can print the AST as a text string
context – Either a list of functions or a context retriever. The list of functions can be a mixture of python callables and Kork external functions. All python functions will be converted into Kork external functions, and everything passed into the default context retriever.
examples – An example retriever or a list of examples. If a list of examples, a simple example retriever will be created.
instruction_template – Use to customize the instruction components of the prompt.
language_name – The language name to use for the prompt.
input_formatter – A formatting that will be applied to the input part of each example tuple, if passing in a list of examples.
input_key – The input key to use.

Returns

A code chain

input_formatter: InputFormatter#: The smirking kat programming language; aka Kork; aka 😼

input_key: str#

instruction_template: PromptTemplate#: Template for the instruction prompt.

interpreter: Callable[[str, Environment], InterpreterResult]#: The interpreter to use for the coding chain.

language_name: str#

llm: BaseLanguageModel#: The language model to use for the coding chain.

memory: Optional[BaseMemory]#

prepare_context(query: str, variables: Optional[Mapping[str, Any]] = None) → Tuple[kork.environment.Environment, kork.prompt_adapter.FewShotTemplate][source]#

Get the pre-populated environment and the few shot template.

Parameters

query – The query to prepare the context for.
variables – Any variables that should be added to the context.

Returns

The prepopulated environment and a pre-formatted few shot template.

verbose: bool#

class kork.Environment(parent: typing.Optional[kork.environment.Environment] = None, variables: typing.Dict[str, typing.Any] = <factory>)[source]#

Bases: object

Environment for storing variables and function definitions.

clone() → kork.environment.Environment[source]#

Clone a root level environment, with deep copy on variables.

Cloning functionality is provided because the environment is a mutable variable.

Biggest danger is mutating the variables dict which the caller may retain a reference to.

TODO(Eugene): Refactor to make this less dangerous.

get_symbol(name: str) → Any[source]#

Get a symbol from the environment.

Parameters: name – symbol name to lookup
Returns: SymbolValue for the given symbol if it exists, otherwise raises an error

list_external_functions() → List[kork.ast.ExternFunctionDef][source]#: Get a list of the externally defined foreign functions.

parent: Optional[kork.environment.Environment] = None#

set_symbol(name: str, value: Any) → Any[source]#: Set a symbol in the environment.

variables: Dict[str, Any]#

class kork.InterpreterResult[source]#

Bases: TypedDict

Use this to return the result of the interpreter.

environment: kork.environment.Environment#

errors: Sequence[Exception]#

exception kork.KorkException[source]#

Bases: Exception

Generic Kork exception.

class kork.SimpleContextRetriever(external_functions: Sequence[kork.ast.ExternFunctionDef] = ())[source]#

Bases: kork.retrieval.AbstractContextRetriever

Retrieve information as was provided without any filtering or re-ranking.

external_functions: Sequence[kork.ast.ExternFunctionDef] = ()#

classmethod from_functions(mixed_funcs: Sequence[Union[kork.ast.ExternFunctionDef, Callable]]) → kork.retrieval.SimpleContextRetriever[source]#

Create a simple retrieval from a sequence of functions.

Parameters: mixed_funcs – A sequence of functions or external function definitions.
Returns: A simple retriever.

retrieve(query: str) → Sequence[kork.ast.ExternFunctionDef][source]#: Retrieve the external function definitions.

class kork.SimpleExampleRetriever(examples: Sequence[Tuple[str, str]])[source]#

Bases: kork.examples.AbstractExampleRetriever

Simple example retriever.

Simple example that returns the examples it was initialized with.

Supports initialization from a list of programs.

Example:

from kork import SimpleExampleRetriever, AstPrinter, c_, r_

simple_example_retriever = SimpleExampleRetriever.from_programs(
    language_name="kork",
    examples=[
        ("add 1 2", r_(c_(add, 1, 2))),
        ("add 1 2 3", r_(c_(add, 1, 2, 3))),
        ],
    ast_printer=AstPrinter(),
)

examples = simple_example_retriever.retrieve("add 1 2")

Create a simple example retriever from programs.

Parameters

language_name – The language name to use for the markdown code blocks.
examples – A sequence of tuples of the form (query, desired program).
ast_printer – The ast printer to use to format the desired output.

Returns

A simple example retriever.

retrieve(query: str) → List[Tuple[str, str]][source]#: Retrieve examples that best match the given query.

kork.c_(name: Callable, *args: Any) → kork.ast.FunctionCall[source]#: Create a kork function call.

kork.format_examples(language_name: str, examples: Sequence[Tuple[str, kork.ast.Program]], ast_printer: kork.ast_printer.AbstractAstPrinter, input_formatter: Union[Literal['text_prefix'], Literal['triple_quotes'], Literal['markdown_text'], None, Callable[[str], str]] = None) → List[Tuple[str, str]][source]#: Format examples.

kork.r_(expr: kork.ast.Expr) → kork.ast.Program[source]#: Assign last program expression to a result variable.

kork.run_interpreter(code: str, environment: Optional[kork.environment.Environment] = None) → kork.interpreter.InterpreterResult[source]#

Run the interpreter with the given code.

Parameters

code – The code to run
environment – The environment to run the code in

Returns

the final environment after running the code (this will likely change)

kork package

Contents

kork package#

Submodules#

kork.ast module#

kork.ast_printer module#

kork.chain module#

kork.display module#

kork.environment module#

kork.examples module#

kork.exceptions module#

kork.foreign_funcs module#

kork.interpreter module#

kork.parser module#

kork.prompt_adapter module#

kork.retrieval module#

kork.utils module#

kork.version module#

Module contents#