Getting Started

1. Log into the app at app.bismuth.cloud. If you haven't signed in before this will create a new account.
   
2. Click the bouncing button in the center of the screen to create your first project. This will ask you for a name, which can be whatever you want, try something memorable like a color and animal combination.
   1. Note: Behind the scenes this creates a git repo and a main branch. We're working on exposing this directly to developers, stay tuned.
      
3. On the left hand side is your chat interface. This is where you chat with our AI, Bismuth for all your backend development needs. Try asking it to:
   1. Please create an API that responds with "Hello Bismuth" at the "/hello" route and wrap the handler in a FunctionCodeBlock.
   2. Note: API route handlers need to be wrapped in a function code block, so double check for this before deploying.
      
4. At this point you should see some code in the chat and something has appeared in the right hand visual interface.
5. The visual editor is where all of our special codeblocks that the model generates are shown.
   1. Note: Specific codeblocks may have settings like for app entrypoints (how we run your code) and scheduable functions.
      
6. Feel free to click and drag around the visual editor to get a feel for it.
7. Now on the top bar there is a tab toggle, if you click into the other tab, you'll see our code editor. As well as a file or two. Click into one of the files.
   
8. Here you can edit and change the contents of your code. Currently we only support python code, and baring specific circumstances the code needs to be in the "src/" folder. Great, on the bar above click the save icon. You should see a green success pop-up.
9. Switch back to the visual editor tab. At this point you should see at least two nodes. One of the nodes should have a checkbox labeled "Entrypoint". Check this box. At this point the project will automatically save again.
   
10. Almost there! Now click the big green play button in the upper bar and you'll notice a few changes. The fairly big one is the new "Invoke URL" bar that has appeared. You can click the copy button next to it to copy to your clipboard. This URL is how you will talk to your API.
    
11. The second change, is a new scroll looking icon will have appeared in the top bar. Clicking this will open a panel below the editor view. This panel receives a live stream of logs from the API you just launched. This is helpful for debugging and generally seeing what is going on with your application.
    
12. Now using the Invoke URL, try making a curl request to the "/hello" route from earlier. If all goes well you should get a 200 response and whatever message you asked it to respond with!
    

Great! Now you should understand how the platform works and give you an idea of what you can start to build. Check out the SDK docs below to see all the available code blocks, or feel free to write your own using the base code block. Bismuth knows about your files and your chat history. Happy building!

Special Files

entrypoint.py

For the Bismuth Cloud to know how to run your code, a special "entrypoint" file is required. This file must live in src/entrypoint.py and instantiate a variable called app which is the root APICodeBlock which should be run. This can be managed via the web UI, or written manually.

cron

Bismuth can run periodic (cron) jobs automatically. Python scripts in the src/bismuth_jobs directory will be treated as cron jobs if they have two special comments: CRON and JOBNAME. An example job could look like:

# BISMUTH FILE: bismuth_jobs/sync_data.py
# CRON: * * * * *
# JOBNAME: sync_data

import requests
...

Bismuth SDK Reference

The SDK consists of codeblocks for accomplishing various common programming tasks. Bismuth knows about each one of these blocks and will automatically try to use them when writing code. Alternatively, you yourself can use them when writing code that will be published on the Bismuth Cloud platform.

Some of these blocks, e.g. PersistentDataStorageCodeBlock, integrate with Bismuth Cloud's hosted services. These can be instantiated anywhere in your application, and provide easy access to data storage, configuration, and SQL.

Full examples of using the SDK can be found in the SDK's repo on GitHub.

module bismuth

Global Variables

1. codeblocks
2. base_code_block
3. configuration
4. api
5. data_storage
6. api_with_storage
7. blob_storage
8. function
9. sql

module bismuth.codeblocks

Global Variables

1. base_code_block
2. configuration
3. api
4. data_storage
5. api_with_storage
6. blob_storage
7. function
8. sql

module bismuth.codeblocks.api

class API

Extends BaseCodeBlock, this class includes methods and attributes for API code blocks.

method __init__

__init__(
    title='API',
    version='1.0',
    description='A simple API',
    config: Optional[Configuration] = None,
    *args,
    **kwargs
)

Initializes the APICodeBlock class with optional title, version, description, and configuration code block. add_route should be called in overrides of this to register routes for the API.

method add_route

add_route(
    route: str,
    handlers: dict[str, Callable[Concatenate[Request, ], Any]]
)

Adds a route to the API. Handlers receive the request from flask plus query parameters as kwargs.

method run

run(host='0.0.0.0', port=5000, debug=False)

Starts the API on the given port and host.

module bismuth.codeblocks.api_with_storage

class APIWithStorage

A class that extends APICodeBlock to include functionalities for data storage. It manages API routes and associates them with specific data storage operations.

method __init__

__init__(*args, **kwargs)

Initializes the APICodeBlockWithStorage instance. Inherits initialization from APICodeBlock and initializes a dictionary to hold DataStorageBlock instances.

method add_route_with_storage

add_route_with_storage(
    route: str,
    methods: List[str],
    data_storage_block: DataStorage,
    require_auth: List[str] = ['POST', 'DELETE', 'PUT'],
    auth_cb: Callable[[Request], bool] = <function APIWithStorage.<lambda> at 0x7ff6dbfd25c0>
)

Adds a route to the API with associated data storage functionality.

module bismuth.codeblocks.base_code_block

class BaseCodeBlock

This class includes base methods and attributes for all other CodeBlocks

method __init__

__init__()

Initializes the base code block.

module bismuth.codeblocks.blob_storage

class BlobStorage

This class exposes Bismuth's blob storage service, allowing data to be persisted. Bytes are stored plain, while other types are stored as JSON. When run locally, it stores data via files in a temporary directory.

method __init__

__init__(api_url='http://169.254.169.254:9000/blob/v1/')

Initialize the datastore.

method create

create(key: str, value: Any) → None

Create a new item in the datastore.

method delete

delete(key: str) → None

Delete an item from the datastore.

method list_keys

list_keys() → set[str]

List all keys in the datastore.

method retrieve

retrieve(key: str) → Optional[Any]

Retrieve an item from the datastore.

method update

update(key: str, value: Any) → None

Update an existing item in the datastore.

module bismuth.codeblocks.configuration

class Configuration

The ConfigurationCodeBlock provides access to runtime configuration set outside the code. Instances of this class expose configuration to the application via the get method, which must be passed a string literal, NOT a variable. All instances of this class must be called config.

method __init__

__init__(api_url='http://169.254.169.254:9000/secrets/v1/')

Initialize the configuration store.

method get

get(key) → Optional[str]

Get a config value. Raises an exception if the key does not exist in the managed configuration store.

module bismuth.codeblocks.data_storage

class DataStorage

Extends BaseCodeBlock. This class manages data storage operations.

method __init__

__init__()

Initialize the datastore with an empty dictionary.

method create

create(key: str, value: Any)

Create a new item in the datastore.

method delete

delete(key: str)

Delete an item from the datastore.

method list_all

list_all()

List all items in the datastore.

method retrieve

retrieve(key: str)

Retrieve an item from the datastore.

method update

update(key: str, value: Any)

Update an existing item in the datastore.

module bismuth.codeblocks.function

class Function

Extends BaseCodeBlock. Run a python function with some requirements.

method __init__

__init__(func: Callable[~P, ~R], network_enabled: bool = False, *args, **kwargs)

Initializes the FunctionCodeBlock with the function callable.

method exec

exec(*args: args, **kwargs: kwargs) → ~R

Run a subset of arbitrary python functions as defined by Bismuth provided args and kwargs.

module bismuth.codeblocks.sql

class SQL

The SQLCodeBlock provides basic access to the Bismuth SQL service.

method __init__

__init__(pg_uri: Optional[str] = None)

method execute

execute(sql: str, params: Union[Sequence[Any], Mapping[str, Any]] = {})

Run the given SQL, returning no results.

method fetchall

fetchall(
    sql: str,
    params: Union[Sequence[Any], Mapping[str, Any]] = {}
) → list[tuple[Any, ]]

Run the given SQL, returning all rows.

method fetchone

fetchone(
    sql: str,
    params: Union[Sequence[Any], Mapping[str, Any]] = {}
) → Optional[tuple[Any, ]]

Run the given SQL, returning a single row.

method getconn

getconn() → Connection

Get the underlying psycopg connection.