Development Guide
Learn how to develop, package, and run your Book locally with the BDK.
Have You Completed the Setup?
Ensure you’ve followed all the steps to set up your BDK project before proceeding. This includes configuring your environment and installing dependencies.
Project Structure
The project is organized with the following structure:
Root Directory
The project root directory is named using the Project Slug (default: sample_book).
Source Code Directory
📃 book.py
: Contains the core class where your Book is defined and implemented.📁 data
: Holds images like🖼️ icon.svg
, the default SVG used as a Book's icon.
Test Directory
📃 test_book.py
: Contains unit tests to validate the Book's functionality.
Configuration and Dependency Files
📃 Dockerfile
: Builds the Docker image.📃 pyproject.toml
: Manages dependencies and settings.📃 poetry_scripts.py
: Custom automation script.📃 poetry.lock
: Locks dependency versions.
Documentation
📃 README.md
: Project overview documentation, including setup and usage instructions.📃 USAGE.md
: Reference documentation for your Book. This file is not included by default. For details on how to generate it, see Generating Documentation.
Implementation
Implement your Book in book.py. This class is auto-generated by the BDK Template and serves as the starting point for your Book’s implementation. Use decorators to configure settings, define procedures, and establish API connections. Refer to the and example Books for details.
Development Commands
This section outlines essential commands for Book development and testing.
Formatting
Code formatting automatically adjusts your code's structure, ensuring adherence to coding standards, readability, and maintainability. To apply the formatting, run:
Linting
Pylint is used as the source linter for BDK projects. The linter analyzes and enforce coding standards, checks for errors in Python code, and improves code quality. To run the linter:
Generating Documentation
This command will generate a comprehensive USAGE.md file by extracting and formatting the docstrings from your code. To generate the documentation, run:
Testing
Pytest is used to test and validate your book. To run the test suite:
Packaging with Docker
Build a Docker image to package your Book:
Architecture Compatibility
This image pulls the BDK Runtime base image from Docker Hub, which is currently available only for the linux/amd64 architecture. If you're using a machine with a different architecture, you can use the --platform
flag to emulate linux/amd64 when building the image:
Running Your Book Locally
To test your Book in Kognitos before deployment, you can run your Docker image locally with ngrok. Ngrok is a tool that creates a secure tunnel to your local machine and provides a public URL to make your local Docker image accessible from the platform.
1. Install ngrok
Follow the installation steps for ngrok based on your system. You will need to sign up for a free account.
2. Obtain your ngrok authtoken
Navigate to Your Authtoken in the ngrok portal and copy your token.
3. Add your authtoken
4. Configure the ngrok api key as an environment variable:
5. Build & run in ngrok mode
This command will invoke a custom script that builds the Docker image and runs it in ngrok mode:
If you are running into issues with `poetry run host`, you can package and run your book manually with the following command:
Make sure to replace auth_token
, project_slug
, and version
with your own values.
6. Copy the URL
You'll see the ngrok address in the following format in the logs. Copy the URL:
7. Add the URL to your automation
Copy the URL and paste it into your Kognitos Playground using this syntax:
If you implemented any custom connections, be sure to connect to your Book after learning it so that you can invoke its procedures.
Last updated
Was this helpful?