LogoLogo
About
  • Home
  • Guides
  • BDK
  • REST API
  • BDK Overview
  • Planning Guide
  • Setup Guide
  • Development Guide
  • Deployment
  • Learning a BDK Book
  • Connection Commands
  • BDK API Reference
    • Concepts
    • Connections
    • Decorators
      • @book
      • @concept
      • @config
      • @connect
      • @oauth
      • @oauthtoken
      • @procedure
    • Docstrings
    • Enums
      • FilterBinaryOperator
      • FilterUnaryOperator
    • Filter Expressions
    • Noun Phrases
    • Procedures
Powered by GitBook
On this page
  • Project Structure
  • Implementation
  • Managing Dependencies
  • Development Commands
  • Packaging with Docker
  • Running Your Book Locally

Was this helpful?

Export as PDF

Development Guide

Learn how to develop, package, and run your Book locally with the BDK.

Last updated 13 days ago

Was this helpful?

Have You Completed the Setup?

Ensure you’ve followed all the steps to your BDK project before proceeding. This includes configuring your environment and installing dependencies.

Project Structure

The project is organized with the following structure:

📂 sample_book
├── 📁 src
│   └── 📁 sample_book
│       ├── 📃 __init__.py
│       ├── 📃 __version__.py
│       └── 📃 book.py
│       └── 📁 data
│           └── 🖼️ icon.svg
├── 📁 tests
│   └── 📃 test_book.py
├── 📃 Dockerfile
├── 📃 pyproject.toml
├── 📃 poetry_scripts.py
├── 📃 poetry.lock
├── 📃 README.md
└── 📃 USAGE.md

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.


Implementation


Managing Dependencies


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:

poetry run format

Linting

poetry run lint

Generating Documentation

poetry run doc

Testing

poetry run tests

Packaging with Docker

Build a Docker image to package your Book:

docker build -t <project_slug>:<version> .

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:

docker build --platform linux/amd64 -t <project_slug>:<version> .

Running Your Book Locally

1. Install ngrok

2. Obtain your ngrok authtoken

Navigate to Your Authtoken in the ngrok portal and copy your token.

3. Add your authtoken

ngrok config add-authtoken <token>

4. Configure the ngrok api key as an environment variable:

export NGROK_AUTHTOKEN=<token>

5. Build & run in ngrok mode

This command will invoke a custom script that builds the Docker image and runs it in ngrok mode:

poetry run host
docker run -e BDK_SERVER_MODE=ngrok -e NGROK_AUTHTOKEN=<auth_token> <project_slug>:<version>

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:

listening on https://<SOME_UUID>.ngrok-free.app

7. Add the URL to your automation

Copy the URL and paste it into your Kognitos Playground using this syntax:

learn "https://f1d7-100-34-252-18.ngrok-free.app"

📃 USAGE.md: Reference documentation for your Book. This file is not included by default. For details on how to generate it, see .

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 BDK API Reference and for details.

is used for Python dependency management in BDK projects. To add an external Python dependency to your project, refer to the command, which adds packages to your pyproject.toml and installs them.

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:

This command will generate a comprehensive USAGE.md file by extracting and formatting the from your code. To generate the documentation, run:

is used to test and validate your book. To run the test suite:

To test your Book in Kognitos before deployment, you can run your Docker image locally with . 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.

Follow the installation steps for based on your system. You will need to sign up for a free account.

If you are running into issues with `poetry run host`, you can and run your book manually with the following command:

If you implemented any custom , make sure you also to your Book after learning.

set up
example Books
Poetry
poetry add
Pylint
docstrings
Pytest
ngrok
ngrok
connections
connect
Generating Documentation
package