Natural Language Features
DuckTape's core strength is its ability to understand natural language commands. This guide explains how to use natural language with DuckTape and provides examples of what you can do.
How It Works
DuckTape uses AI language models to parse your natural language commands and convert them into structured actions. This allows you to interact with your Apple Calendar, Reminders, and Notes using everyday language rather than memorizing specific command syntax.
Natural Language Processing Flow
Input Analysis
Your natural language command is analyzed for intent and key information.
Entity Extraction
DuckTape identifies important details like dates, times, contacts, and locations.
Command Translation
The natural language is translated into a specific DuckTape command.
Action Execution
The corresponding action is executed in your calendar, reminders, or notes.
🦆 DuckTape breaks down your natural language command, determines your intent, extracts important entities like dates and names, and then executes the appropriate action.
Language Model Configuration
Supported Language Models
| Provider | API Key Environment Variable | Config Setting | Notes |
|---|---|---|---|
| Grok (X.AI) | XAI_API_KEY |
provider = "Grok" |
Primary provider with excellent understanding of date/time expressions |
| DeepSeek | DEEPSEEK_API_KEY |
provider = "DeepSeek" |
Alternative option with support for similar features |
Setting Up Language Models
Follow these steps to configure a language model provider:
- Obtain an API key from your chosen provider (X.AI for Grok or DeepSeek)
- Set the environment variable for your chosen provider:
# For Grok (X.AI) export XAI_API_KEY='your-xai-api-key-here' # For DeepSeek export DEEPSEEK_API_KEY='your-deepseek-api-key-here' - Edit your config.toml file to specify the provider:
[language_model] provider = "Grok" # Options: "Grok", "DeepSeek"
Switching Between Providers
To change language model providers:
- Ensure you have the appropriate API key set in your environment
- Update the
providerfield in yourconfig.toml - Restart DuckTape if it's already running
Disabling Natural Language Mode
If you want to use DuckTape in Terminal Mode (without natural language processing):
- Comment out the provider line in your config.toml:
[language_model] # provider = "Grok" # Comment out the provider to disable Natural Language Mode - Or set it to an empty string:
[language_model] provider = "" # Empty string disables Natural Language Mode
Troubleshooting
If you see API key errors:
- Verify that the environment variable is correctly set
- Check if your API key has expired or has been revoked
- Try echoing the environment variable to confirm it's set:
echo $OPENAI_API_KEY - Make sure the API key is associated with an account that has usage permissions
- Ensure your config.toml has the correct format
- Verify the provider name is spelled correctly with the same capitalization shown above
- Check the location of your config.toml file (should be in the DuckTape root directory)
- Try running
ducktape config showto see the current configuration
- Check if DuckTape is starting in Terminal Mode instead of Natural Language Mode
- Verify internet connectivity (language models require internet access)
- Try a simple command to test if the language model is responding
- Check for API rate limiting or quota issues
- Review the logs for specific error messages with
ducktape --debug
Command Structure
To use natural language features, simply start DuckTape and type your request as you would speak it:
Tips for Clear Commands
While DuckTape is designed to understand a wide range of expressions, these tips can help ensure your commands are understood correctly:
- Be specific about dates, times, and durations
- Mention the calendar or reminder list name if you're not using the default
- Include key information like attendees, location, and purpose
- Use clear action verbs: "schedule," "create," "add," "remind," etc.
Natural Language Capabilities
DuckTape can understand a wide variety of date and time expressions:
- Relative dates: "tomorrow," "next Tuesday," "in 3 days"
- Specific dates: "January 15th," "11/20/2025"
- Time expressions: "3pm," "15:30," "morning," "noon"
- Duration: "for 1 hour," "30 minutes," "all day"
- Combined: "next Monday at 9am for 2 hours"
Examples:
- "Schedule a dentist appointment next Friday at 2pm"
- "Add a meeting on March 15th from 10am to noon"
- "Remind me about the presentation tomorrow morning"
DuckTape can understand and create recurring events with various patterns:
- Weekly: "every Monday," "weekly"
- Monthly: "first Tuesday of every month," "monthly"
- Yearly: "annually," "every year on March 15th"
- Custom: "every other Friday," "every weekday"
- With end dates: "weekly until December," "every Monday for the next 10 weeks"
Examples:
- "Schedule a team meeting every Tuesday at 10am called budget review"
- "Create a weekly staff check-in on Fridays at 4pm"
- "Add a reminder to pay rent on the 1st of every month"
DuckTape can target specific calendars and reminder lists:
- Calendar selection: "add to my Work calendar," "in my Personal calendar"
- List selection: "add a reminder to my Shopping list," "in my Personal reminders"
- Contextual selection: DuckTape can infer the appropriate calendar based on the event type
Examples:
- "Add a doctor's appointment to my Health calendar for next Tuesday"
- "Schedule a team meeting in my Work calendar every Monday"
- "Add 'buy milk' to my Groceries reminder list"
DuckTape can handle meeting invitations and attendees:
- Adding attendees: "with John and Sarah," "invite the marketing team"
- Email invites: "invite john@example.com and sarah@example.com"
Examples:
- "Schedule a product review tomorrow at 3pm with Joe Bloggs"
- "Create a meeting for next Monday at 9am inviting joe.bloggs@example.com"
Examples of Natural Language Commands
- Fixed time parsing in natural language commands with specific time expressions
- Improved AM/PM to 24-hour time conversion for calendar events
- Enhanced contact extraction functionality for calendar events
- Added support for "and invite" pattern in natural language commands
- Improved error handling and stability for calendar operations
Calendar Events
- Create a standard calendar event with a contact:
create an event Team Meeting with Joe Duck for this coming Tuesday - Create a calendar event with Zoom integration and invite a contact:
create a zoom event today at 10am called Team Check in and invite Joe Duck - Create an event with a contact, specific time, and description:
schedule a meeting with Joe Duck tomorrow at 2pm about project review - Create a recurring weekly event:
create a weekly team meeting every Tuesday at 10am - Create an event in a specific calendar:
schedule a dentist appointment next Friday at 2pm in my Health calendar - Create an event with a specific duration and invite a contact:
create an event called Quarterly Review next Monday from 2-4pm and invite Jane Doe
Reminders
- Create a reminder with a specific time:
create a reminder today at 11pm called Check if Ducks are swimming - Create a reminder for a future date with a general time period:
add a reminder to buy groceries next Monday morning - Create a reminder with a specific date and time:
remind me to call Joe Duck on Friday at 3pm - Create a reminder for a specific task with exact time:
set a reminder for tomorrow at noon to review documents - Add a reminder to a specific list:
add "buy milk" to my Shopping list
Notes
- Create a note with a title and specific content:
create a note titled "Meeting Ideas" with content about product planning - Create a simple note with a descriptive title:
add a note about the new marketing strategy - Create a general note:
create a note with my shopping list
- Precise times: "3pm", "15:30", "morning", "noon"
- Relative dates: "tomorrow", "next Tuesday", "in 3 days"
- Specific dates: "January 15th", "11/20/2025"
- Combined: "next Monday at 9am for 2 hours"
Advanced Language Features
Context Retention
DuckTape remembers context from previous commands, allowing for more natural conversations about related tasks.
You: Schedule a meeting with John
DuckTape: When would you like to schedule this meeting?
You: Tomorrow at 2pm
DuckTape: Creating meeting with John for tomorrow at 2:00 PM...
Clarification Questions
When information is missing, DuckTape will ask for clarification to complete your request properly.
You: Create a recurring meeting
DuckTape: What day and time would you like for this recurring meeting?
You: Every Monday at 10am
DuckTape: Creating recurring meeting for every Monday at 10:00 AM...
Calendar Conflicts
DuckTape can detect scheduling conflicts and suggest alternatives based on your calendar.
You: Schedule a meeting tomorrow at 2pm
DuckTape: You already have an event "Budget Review" at that time. Would you like to schedule for 3:00 PM instead?
You: Yes, that works
DuckTape: Creating meeting for tomorrow at 3:00 PM...
Terminal Navigation Commands
DuckTape includes commands to help you navigate and control the application itself. These commands work in both Terminal Mode and Natural Language Mode.
Exiting DuckTape
You can exit DuckTape at any time using any of these commands:
exit
quit
ducktape exit
ducktape quit
New in v0.12.1: Exit commands now work reliably in both Terminal Mode and Natural Language Mode. Previously, in Natural Language Mode, exit commands might not work if there were API issues with the language model.
Getting Help
To see available commands and examples:
help
ducktape help
ducktape help [command]
- Improved detection of calendar event creation intent
- Better handling of event titles and contact information
- Enhanced pattern matching for time expressions like "tonight at 10pm"
- More reliable parsing of natural language commands in interactive mode
- Direct fallback patterns for common natural language expressions