What are Concepts?

Concepts define how data flows in out of an operation:

• Input concepts represent the inputs that an operation requires.
• Output concepts represent the results that an operation 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:

Custom Types

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

@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

Concepts are operated on by Kognitos operations. Some concepts are included in the name of the @procedure decorator.

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?

There is an internal mapping that gets created between a Python function and a Kognitos operation. To ensure a correct mapping, concepts and parameters must match.

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. Consider each connected noun phrase as a separate parameter. Non-essential noun phrases (e.g., "field," "value") included to clarify context do not require a corresponding parameter.
4. Don't map articles ('an', 'a', 'the') to parameters; only the nouns they connect should be considered.
5. 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 parenthesis 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
    """