Skip to content

Core Functions API Reference

⚠️ IMPORTANT FOR AI CODE GENERATORS: These are the official type signatures for Dana's core functions. Use these signatures when generating Dana code to ensure proper type checking and better code quality.

Dana provides essential core functions that are automatically available in all Dana programs. These functions have well-defined type signatures that help AI code generators write better Dana code.

Table of Contents

AI/Reasoning Functions

reason(prompt: str, options: dict = {}) -> str

LLM-powered reasoning and analysis function.

Parameters: - prompt: str - The question or prompt to send to the LLM - options: dict - Optional parameters for LLM configuration - temperature: float - Controls randomness (0.0-1.0, default: 0.7) - max_tokens: int - Maximum response length - format: str - Output format ("text" or "json") - system_message: str - Custom system message

Returns: str - The LLM's response to the prompt

Examples: 

# Basic reasoning
analysis: str = reason("What is the weather like today?")

# With options for structured output
result: str = reason("Analyze this data", {
 "temperature": 0.3,
 "max_tokens": 200,
 "format": "json"
})

# Complex reasoning with context variables
temp: float = 75.5
humidity: int = 60
assessment: str = reason(f"Given temperature {temp}°F and humidity {humidity}%, is this comfortable?")

# Using system message for context
analysis: str = reason("What should I do next?", {
 "system_message": "You are a helpful assistant for project management.",
 "temperature": 0.5
})

Security Notes: - The reason() function operates within the sandbox security model - Prompts are sanitized before being sent to the LLM - Response content is validated and safe for use in Dana programs

Related Functions: - log() - For logging reasoning operations - print() - For displaying reasoning results

Output Functions

print(*args: any) -> None

Print multiple values to standard output with space separation.

Parameters: - *args: any - Variable number of arguments of any type to print

Returns: None

Examples: 

# Print literals
print("Hello", "World", 123)
# Output: Hello World 123

# Print variables
name: str = "Alice"
age: int = 25
print("Name:", name, "Age:", age)
# Output: Name: Alice Age: 25

# Print expressions
x: int = 10
y: int = 20
print("Sum:", x + y)
# Output: Sum: 30

# Print complex data structures
user_data: dict = {"name": "Bob", "score": 95}
print("User data:", user_data)
# Output: User data: {'name': 'Bob', 'score': 95}

# Print multiple types
is_active: bool = true
scores: list = [85, 92, 78]
print("Active:", is_active, "Scores:", scores)
# Output: Active: true Scores: [85, 92, 78]

Behavior: - Arguments are converted to string representation - Multiple arguments are separated by single spaces - Automatically adds newline at the end - Handles all Dana data types (int, float, str, bool, list, dict, tuple, set, None)

Related Functions: - log() - For structured logging instead of simple output

Logging Functions

log(message: str, level: str = "info") -> None

Log a message with the specified level.

Parameters: - message: str - The message to log - level: str - Log level ("debug", "info", "warn", "error", default: "info")

Returns: None

Examples: 

# Basic logging (info level)
log("Processing started")

# Different log levels
log("Debug information", "debug")
log("Operation completed successfully", "info")
log("Warning: High temperature detected", "warn")
log("Error occurred during processing", "error")

# Logging with variables
user_name: str = "Alice"
operation: str = "data_analysis"
log(f"Starting {operation} for user {user_name}", "info")

# Logging complex data
result: dict = {"status": "success", "count": 42}
log(f"Operation result: {result}", "info")

Log Levels: - "debug" - Detailed information for debugging - "info" - General information about program execution - "warn" - Warning messages for potential issues - "error" - Error messages for serious problems

Behavior: - Messages are formatted with timestamp and level - Log output depends on current log level setting (see log_level()) - Messages below the current log level are filtered out

Related Functions: - log_level() - Set global logging level - print() - For simple output without log formatting

log_level(level: str, namespace: str = "dana") -> None

Set the logging level for a specific namespace in the Dana runtime.

Parameters: - level: str - The log level to set ("debug", "info", "warn", "error") - namespace: str - The namespace to set the level for (default: "dana")

Returns: None

Examples: 

# Set to show all messages in dana namespace
log_level("debug", "dana")
log("This debug message will be shown", "debug")

# Set to show only warnings and errors in dana namespace
log_level("warn", "dana")
log("This info message will be hidden", "info")
log("This warning will be shown", "warn")

# Set to show only errors in dana namespace
log_level("error", "dana")
log("This warning will be hidden", "warn")
log("This error will be shown", "error")

# Set level for opendxa namespace (framework code)
log_level("error", "opendxa")

# Typical usage pattern
log_level("info", "dana") # Set appropriate level for production
log("Application started", "info")

Log Level Hierarchy: 1. "debug" - Shows all messages (debug, info, warn, error) 2. "info" - Shows info, warn, error (hides debug) 3. "warn" - Shows warn, error (hides debug, info) 4. "error" - Shows only error messages

Logging Scopes

Dana uses two separate logging scopes to organize log messages:

  • "dana" - User code logs (default scope)
  • Used for logs from your Dana programs
  • Default level is "info"

  • Example: log("Processing data", "info")

  • "opendxa" - Framework code logs

  • Used for internal OpenDXA framework messages
  • Default level is "warn"
  • Example: Framework initialization and system messages
# Set different levels for different scopes
log_level("debug", "dana")    # Show all user code logs
log_level("error", "opendxa") # Show only framework errors

# User code logs (dana scope)
log("Starting application", "info")
log("Debug info", "debug")

# Framework logs (opendxa scope) - only errors will show

Best Practices: - Use "debug" for dana scope during development - Use "info" for dana scope in production - Use "error" for opendxa scope to reduce framework noise - Set appropriate levels for each scope independently

Related Functions: - log() - Log messages at specific levels

Function Lookup Precedence

Dana follows a clear precedence order when resolving function calls:

  1. User-defined functions (highest priority) - Functions defined in the current Dana file
  2. Core functions (medium priority) - Essential Dana functions documented above
  3. Built-in functions (lowest priority) - Pythonic built-ins like len(), sum(), max()

This ensures that: - User code can override any built-in function if needed - Core Dana functions maintain their essential behavior - Built-in functions provide familiar Python-like functionality

Example: 

# User-defined function overrides built-in
def len(obj):
 return "custom length function"

# This calls the user-defined function, not the built-in
result = len([1, 2, 3]) # Returns "custom length function"

# Core functions like reason() cannot be overridden for security
analysis = reason("What should I do?") # Always calls core function

Type Safety Guidelines

When using core functions in Dana code:

  1. Always specify types for variables that will be passed to core functions
  2. Use type hints on function parameters and return values
  3. Validate return types when assigning core function results
  4. Handle optional parameters explicitly when using options dictionaries

Example of well-typed core function usage: 

# Type-safe core function usage
def analyze_data(data: dict, query: str) -> dict:
 # Log the operation with proper types
 log(f"Analyzing data with query: {query}", "info")

 # Get AI analysis with typed options
 options: dict = {
 "temperature": 0.5,
 "format": "json",
 "max_tokens": 500
 }
 analysis: str = reason(f"Analyze this data: {data} for: {query}", options)

 # Print results with type safety
 print("Analysis complete:", analysis)

 # Return structured result with proper typing
 result: dict = {
 "query": query,
 "analysis": analysis,
 "status": "complete",
 "timestamp": "2025-01-01T12:00:00Z"
 }
 return result

# Usage with type hints
user_data: dict = {"name": "Alice", "age": 25, "role": "engineer"}
search_query: str = "performance analysis"
result: dict = analyze_data(user_data, search_query)

Implementation Status

Function Type Signature Status Notes
reason() (prompt: str, options: dict = {}) -> str ✅ Complete Full LLM integration with options
print() (*args: any) -> None ✅ Complete Variadic arguments, any types
log() (message: str, level: str = "info") -> None ✅ Complete Multiple log levels supported
log_level() (level: str, namespace: str = "dana") -> None ✅ Complete Global log level configuration and logging scopes
📖 For implementation details and examples, see the core function modules in opendxa/dana/sandbox/interpreter/functions/core/
---

See Also

Copyright © 2025 Aitomatic, Inc. Licensed under the MIT License.
https://aitomatic.com