@procedure("to add two numbers")
def add_numbers(a: int, b: int = 0) -> int:
"""
Adds two numbers together.
Args:
a: The first number.
b: The second number. Defaults to 0.
"""
return a + b
2. Return Values
Documents the return value of a function or method.
Supported Headers: Returns
Example
@procedure("to send an *SMS* message")
def send_sms_message(self, sender_number: str, recipient_number: str, message_body: str) -> Optional[str]:
"""
Sends an SMS message using the Twilio API.
Returns:
The SID of the sent message if successful, otherwise None.
"""
3. Error Handling
Lists any exceptions or errors that a function might raise.
Supported Headers: Raises, Exceptions, Except
Example
@timeout.setter
def timeout(self, timeout: float):
"""
Sets the timeout value in milliseconds.
Args:
timeout (int): The timeout value to set. Must be a positive integer.
Raises:
ValueError: If the timeout value is less than or equal to 0.
"""
if timeout <= 0:
raise ValueError("timeout must be positive")
self._timeout = timeout
4. Instance Attributes
List instance attributes in a class.
Supported Headers: Attributes
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
5. Code Authors
Attributes the author(s) of the code.
Supported Headers: Author
Example
@book(name="Sample Book")
class SampleBook:
"""
A book shown as an example.
Author:
Kognitos
"""
6. Labels
Defines labeled data associated with a function related to connections.
Supported Headers: Labels
Example
@connect(noun_phrase="api keys")
def connect(self, api_key: str):
"""
Authenticate to Open Weather API using the specified API key.
Labels:
api_key: API Key
"""
7. OAuth Labels
Describes OAuth labels for classes decorated with the @oauth decorator.
Supported Headers: OAuth Labels
Example
@oauth(
id="oauth",
provider=OAuthProvider.MICROSOFT,
flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
scopes=[
"https://graph.microsoft.com/Files.ReadWrite",
"https://graph.microsoft.com/Sites.Manage.All",
"https://graph.microsoft.com/Sites.ReadWrite.All",
"https://graph.microsoft.com/User.ReadWrite.All",
"https://graph.microsoft.com/Directory.ReadWrite.All",
"https://graph.microsoft.com/Group.ReadWrite.All",
"https://graph.microsoft.com/GroupMember.ReadWrite.All",
"https://graph.microsoft.com/Mail.ReadWrite",
"https://graph.microsoft.com/Mail.ReadWrite.Shared",
"https://graph.microsoft.com/Mail.Send",
"https://graph.microsoft.com/Calendars.ReadWrite",
],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
"""
Base class for all Microsoft Books.
OAuth Arguments:
TENANT_ID: The tenant ID of the Azure AD directory.
OAuth Labels:
TENANT_ID: Tenant ID
"""
8. OAuth Arguments
Describes OAuth arguments for classes decorated with the @oauth decorator.
Supported Headers: OAuth Arguments
Example
@oauth(
id="oauth",
provider=OAuthProvider.MICROSOFT,
flows=[OAuthFlow.AUTHORIZATION_CODE, OAuthFlow.CLIENT_CREDENTIALS],
authorize_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/authorize",
token_endpoint="https://login.microsoftonline.com/{TENANT_ID}/oauth2/v2.0/token",
scopes=[
"https://graph.microsoft.com/Files.ReadWrite",
"https://graph.microsoft.com/Sites.Manage.All",
"https://graph.microsoft.com/Sites.ReadWrite.All",
"https://graph.microsoft.com/User.ReadWrite.All",
"https://graph.microsoft.com/Directory.ReadWrite.All",
"https://graph.microsoft.com/Group.ReadWrite.All",
"https://graph.microsoft.com/GroupMember.ReadWrite.All",
"https://graph.microsoft.com/Mail.ReadWrite",
"https://graph.microsoft.com/Mail.ReadWrite.Shared",
"https://graph.microsoft.com/Mail.Send",
"https://graph.microsoft.com/Calendars.ReadWrite",
],
)
@book(name="MicrosoftBook")
class BaseMicrosoftBook:
"""
Base class for all Microsoft Books.
OAuth Arguments:
TENANT_ID: The tenant ID of the Azure AD directory.
OAuth Labels:
TENANT_ID: Tenant ID
"""
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
"""
Fetch the current temperature for a specified city.
Input Concepts:
the city: The name of the city. Please refer to ISO 3166 for the state codes or country codes.
the unit: Unit of measurement. standard, metric and imperial units are available. If you do
not specify the units, metric units will be applied by default.
"""
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
"""
Fetch the current temperature for a specified city.
Output Concepts:
the current temperature: The current temperature in the specified units of measurement, or None if an error occurs.
"""
11. Examples
Outlines usage examples for a procedure.
Supported Headers: Example, Examples, Example [1-5]
Example
@procedure("to get the (current temperature) at a city")
def current_temperature(self, city: NounPhrase, unit: Optional[NounPhrase] = NounPhrase("metric")) -> float:
"""
Fetch the current temperature for a specified city.
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
"""
