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
  • What are Concepts?
  • Concept Types
  • Standard Types
  • Custom Types
  • Concepts vs. Parameters
  • Concepts
  • Parameters
  • Concept-Parameter Matching
  • Guidelines
  • Example 1
  • Example 2
  • Example 3
  • Example 4
  • Example 5

Was this helpful?

Export as PDF
  1. BDK API Reference

Concepts

Understand concepts and how they are utilized in procedures defined by BDK.

What are Concepts?

Concepts define how data flows in and out of a procedure:

  • Input concepts represent the inputs that a procedure requires.

  • Output concepts represent the results that a procedure generates.

Concept Types

Input and output concepts can be defined as either standard or custom types.

Standard Types

The following Python data types can be used to define concepts:

Category
Supported Python Data Types

Text

str

Number

float, int

Boolean

bool

Bytes

bytes

Date

datetime.datetime, datetime.date, datetime.time

File

typing.IO

UUID

uuid.UUID

Table

pyarrow.Table, arro3.core.Table, nanoarrow.ArrayStream

Lists

List[str], List[int]

Dictionary

Dict[str, Any]

Note:Anycan be any of the other supported types.

Custom Types

@concept(is_a="office user")
@dataclass
class OfficeUser:
    """
    An Office User represents a user in the Microsoft Graph. It includes key user details such as display name,
    email address, and job title.

    Attributes:
        id: The unique identifier for the user.
        display_name: The name displayed in the address book for the user.
        email_address: The user's email address (usually their user principal name).
        job_title: The user's job title.
    """

    id: str
    display_name: Optional[str] = None
    email_address: Optional[str] = None
    job_title: Optional[str] = None
    ...

Concepts vs. Parameters

Concepts and parameters are two different entities that are closely related.

Concepts

Parameters

Parameters are operated on by Python functions. They are defined in a function's signature and are specific to the function's implementation.

How Are They Related?


Concept-Parameter Matching

Concepts and parameter names must match to ensure they are properly mapped internally.

Guidelines

Match concepts to parameters by following these guidelines:

  1. Replace spaces with underscores.

  2. Drop possessive constructions ('s).

  3. Don't map articles ('an', 'a', 'the') to parameters; only the nouns they connect should be considered.

  4. Define optional parameters in cases where the input concept is not explicitly defined in the procedure name.

Example 1

In this example, the concept red car maps to the parameter red_car. The space is replaced with an underscore.

@procedure("to start a red car")
def unique_function_name(self, red_car: type) -> output_type:

Example 2

In the example below:

  • servicenow's ticket maps to ticket

  • field maps to field

  • outlook's standard user maps to standard_user

@procedure("to send a servicenow's ticket's field to an outlook's standard user)
def func(self, ticket: Ticket, field: NounPhrase, standard_user: OutlookUser):

Example 3

In this example, the concept ticket maps to the parameter ticket. The possessive construct ('s) is dropped and the word "field" is ignored.

@procedure("to update a ticket's field")
def update_field(self, ticket: Ticket, new_value: Any):

Example 4

In the example below, the concept of priority is not explicitly stated in the procedure name. It maps to the optional function parameter, priority.

@procedure("to assign the task to the user")
def assign_task(self, task: Task, user: User, priority: Optional[str] = None) -> None:
  """Assign a task to a user.

  Input Concepts:
    the task: The action of piece of work that needs to be completed. 
    the user: The user that the action is to be assigned to.
    the priority: The level of importance or urgency of the task.
    
  Example 1:
    Assign the task to the user

    >>> assign the task to the user

  Example 2:
    Assign the task to the user with a priority

    >>> assign the task to the user with
          the priority is "high"
  """

Example 5

In this example:

  • the city maps to the parameter city

  • the unit maps to the optional parameter the unit

The output concept, current temperature, is wrapped in parentheses in the procedure name.

@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("standard")) -> float:
    """Fetch the current temperature for a specified city.

    Input Concepts:
        the city: The name of the city.
        the unit: Unit of measurement.

    Output Concepts:
        the current temperature: The current temperature in the specified units of measurement, or None if an error occurs.

    Example 1:
        Retrieve the current temperature at London

        >>> get the current temperature at London

    Example 2:
        Retrieve the current temperature at London in Celsius

        >>> get the current temperature at Buenos Aires with
        ...     the unit is metric
    """

Last updated 1 month ago

Was this helpful?

Concepts can also be custom types. Custom concepts must be marked with the decorator. Using a is recommended. For example:

Concepts are operated on by Kognitos procedures. Some concepts are included in the name of the decorator.

An internal mapping is created between a Python function and a Kognitos procedure. To ensure a correct mapping, concepts and parameters must .

Consider each connected as a separate parameter. Non-essential noun phrases (e.g., "field," "value") included to clarify context do not require a corresponding parameter.

@concept
dataclass
noun phrase
@procedure
match