Quickstart

Nightjar ships as the nightjarpy package. Install it directly from PyPI:

pip install nightjarpy

Writing natural code

The @nj.fn decorator turns an ordinary Python function into one whose body is implemented in natural language. Use <variable> to reference state and <:new_variable> to produce new values.

import nightjarpy as nj

@nj.fn
def calculate_average(numbers):
    """natural
    Consider the values of <numbers>
    and compute the semantic average as <:result>
    """
    return result

print(calculate_average([1, "2", "three", "cuatro", "五"]))

Working with objects

Natural blocks share the heap of th Python program, meaning you can use natural code to inspect and update Python objects.

import nightjarpy as nj

class Email:
    def __init__(self, subject, body, sender):
        self.subject = subject
        self.body = body
        self.sender = sender
        self.category = None
        self.priority = None

email = Email("URGENT: Server down", "...", "ops@company.com")

@nj.fn
def categorize_email(email: Email):
    """natural
    Analyze the <email> content and assign its
    category plus a priority. Update the object in place.
    """

categorize_email(email)
print(email.category, email.priority)

Control flow

Natural code can implement control flow in the Python program. It can raise exceptions, break and continue loops, and return from functions.

@nj.fn
def use_heal_item(player):
    for item in player.inventory:
        """natural
        Check if <item> can heal the <player>. If it can, break.
        """
    player.health += item.strength
    player.inventory.remove(item)

Configuration

Nightjar exposes a simple config object for tuning LLM calls per function.

import nightjarpy as nj

config = nj.DEFAULT_CONFIG
config.llm = nj.LLMConfig(
    model="openai/gpt-4o",
    temperature=0,
)

@nj.fn(config=config)
def complex_calculation(data):
    """natural
    Find the outliers in <data> and save as <:outliers>
    """
    return outliers

Set environment variables to authenticate with providers:

OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...

Tips

• Natural blocks are executed with LLM APIs, so costs scale with usage.
• Nightjar performs arbitrary code execution, so sandbox programs for safety.