> ## Documentation Index
> Fetch the complete documentation index at: https://docs.triform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Defining Projects with Triton

> Structure and plan your Projects through conversation

## Overview

Before building, it's helpful to define the high-level structure and goals of your Project. Triton can help you think through requirements, design decisions, and component architecture.

## Starting a new Project definition

### Describe the goal

Begin with what you want to accomplish:

**Examples:**

* *"I need a system that monitors social media for brand mentions and sends alerts"*
* *"I want to build a customer onboarding workflow that sends emails, provisions accounts, and notifies the team"*
* *"I'm building a content moderation system that flags inappropriate posts"*

Triton will ask clarifying questions:

* What inputs does it need?
* What outputs should it produce?
* What external services will it use?
* What's the expected volume/frequency?

### Sketch the architecture

Let Triton help you structure it:

**You:** *"I want to build a research assistant that gathers information from multiple sources"*

**Triton might propose:**

```
Project: Research Assistant
├── Input: Research query, sources list
├── Flow: Orchestration
│   ├── Action: fetch_from_source (for each source)
│   ├── Agent: synthesize_results
│   └── Action: format_output
└── Output: Formatted research report
```

You can then refine: *"Actually, add a validation step to filter low-quality sources first"*

## Defining component types

Triton helps you choose the right component for each task.

### When to use Actions

**Criteria:**

* Deterministic logic
* API calls
* Data transformation
* File operations

**Ask:** *"Should this be an Action or an Agent?"*

**Example:**\
*"I need to validate email addresses and check if they're on our blocklist"*\
**Triton:** This should be an Action—it's deterministic validation logic.

### When to use Agents

**Criteria:**

* Natural language processing
* Decision-making with context
* Creative generation
* Tool orchestration

**Ask:** *"Do I need an Agent here?"*

**Example:**\
*"I need to read customer feedback and categorize it into themes"*\
**Triton:** Yes, an Agent is appropriate—it requires understanding nuanced text.

### When to use Flows

**Criteria:**

* Multi-step processes
* Branching logic
* Parallel operations
* Composing other components

**Ask:** *"How should I structure this workflow?"*

**Example:**\
*"I need to process uploads, validate them, store them, and notify users"*\
**Triton:** Create a Flow with:

1. Input (file upload)
2. Validation Action
3. Storage Action
4. Notification Action
5. Output (confirmation)

## Defining inputs and outputs

Be clear about data shapes upfront:

### Input definition

**You:** *"My Project will receive user requests"*

**Triton:** *"What fields will each request have?"*

**You:** *"User ID, request type, and optional parameters"*

**Triton proposes:**

```json theme={null}
{
  "user_id": "string (required)",
  "request_type": "enum: ['support', 'feature', 'bug'] (required)",
  "parameters": "object (optional)",
  "priority": "enum: ['low', 'medium', 'high'] (default: 'medium')"
}
```

### Output definition

**You:** *"It should return a status and details"*

**Triton proposes:**

```json theme={null}
{
  "status": "enum: ['success', 'pending', 'failed']",
  "message": "string",
  "details": {
    "ticket_id": "string",
    "assigned_to": "string",
    "estimated_resolution": "ISO 8601 datetime"
  }
}
```

## Defining dependencies

Clarify what external resources you'll need:

### API dependencies

**You:** *"I need to integrate with Stripe and SendGrid"*

**Triton notes:**

* Actions will need `stripe` and `sendgrid` Python packages
* Project Variables needed: `STRIPE_API_KEY`, `SENDGRID_API_KEY`
* Rate limits to consider: Stripe (100/sec), SendGrid (varies by plan)

### Data dependencies

**You:** *"The system needs access to our product catalog"*

**Triton asks:**

* How is the catalog stored? (Database, API, file)
* How often does it change?
* Should we cache it?

### Authentication requirements

**You:** *"Users need to authenticate before making requests"*

**Triton suggests:**

* Add authentication Action or use built-in API key validation
* Define user roles if needed
* Handle token refresh if using OAuth

## Defining error handling

Plan for failures upfront:

**You:** *"What if the API call fails?"*

**Triton proposes:**

* Retry logic with exponential backoff
* Fallback to cached data if available
* Return graceful error message
* Log failure for monitoring

**You:** *"What if the input is malformed?"*

**Triton suggests:**

* Validation Action at Flow entry
* Return 400 error with clear message
* Log validation failures

## Defining scale and performance

Think about volume:

**You:** *"I expect about 1000 requests per day"*

**Triton notes:**

* Sequential processing is fine
* No special optimization needed
* Standard quotas should cover this

**You:** *"Actually, 1000 requests per hour during peak times"*

**Triton adjusts:**

* Consider parallel processing
* Add caching layer
* Monitor for rate limits
* Use batching where possible

## Example: Complete definition session

### You

*"I want to build a meeting notes processor"*

### Triton

What should it do with the meeting notes?

### You

*"Take transcripts, extract action items, identify owners, and send reminders"*

### Triton proposes

**Project: Meeting Notes Processor**

**Input:**

```json theme={null}
{
  "transcript": "string (long text)",
  "participants": ["string"],
  "meeting_date": "ISO 8601 datetime"
}
```

**Components:**

1. **Agent: extract\_action\_items**
   * Input: transcript, participants
   * Output: list of action items with owners and due dates
   * Tools: none needed

2. **Action: validate\_participants**
   * Input: participants list
   * Output: validated participants with contact info
   * External: Query user database

3. **Action: send\_reminders**
   * Input: action items with owners
   * Output: reminder status
   * External: Email service (SendGrid)

4. **Flow: orchestration**
   * validate\_participants → extract\_action\_items → send\_reminders

**Output:**

```json theme={null}
{
  "action_items": [
    {
      "description": "string",
      "owner": "string",
      "due_date": "ISO 8601 date",
      "reminder_sent": "boolean"
    }
  ],
  "summary": "string"
}
```

**Dependencies:**

* OpenAI/Anthropic API for Agent
* SendGrid for emails
* User database access

**Error handling:**

* If participant validation fails: continue with available participants
* If email sending fails: log and retry later
* If extraction fails: return transcript with error message

### You

*"Perfect! Let's build it."*

### Triton

I'll start with the `extract_action_items` Agent...

## Best practices for defining

> **Think through errors early** — It's easier to plan for failures than to add handling later

> **Be specific about data types** — Clear schemas prevent integration issues

> **Consider the happy path and edge cases** — Don't just think about perfect inputs

> **Start simple, then elaborate** — Define core functionality before adding features

> **Ask "what if"** — What if the API is down? What if input is huge? What if...

## Common definition anti-patterns

### ❌ Too vague

*"Make something that does AI stuff with data"*

### ✅ Specific

*"Create a Project that takes CSV files, extracts customer sentiment from a 'feedback' column, and returns a summary with positive/negative/neutral counts"*

***

### ❌ Skipping error handling

*"Just build it to work"*

### ✅ Planning for failure

*"Add retry logic for API calls, validation for inputs, and graceful degradation if the ML model is unavailable"*

***

### ❌ No clear boundaries

*"It should do everything related to customers"*

### ✅ Focused scope

*"This Project handles customer onboarding: account creation, welcome email, initial setup wizard. Support and billing are separate Projects"*

## Next steps

Once you've defined your Project, continue with:

1. Building it with Triton
2. Editing and refining components

Explore the Triton documentation for more details on these topics.