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

# Appendix A: Primitives Reference

This appendix provides a quick reference for the foundational concepts covered throughout the book.

## The Ten Elements

| Element          | Definition                                               | Key Insight                                         |
| ---------------- | -------------------------------------------------------- | --------------------------------------------------- |
| **Context**      | The complete information available for a single LLM call | Context is ephemeral—reconstructed every call       |
| **Memory**       | Persistent storage across calls                          | Memory stores; context loads                        |
| **Agency**       | The ability to cause effects beyond text                 | Agency = causality, not just text generation        |
| **Reasoning**    | Structured thinking for complex problems                 | Split generation and evaluation into separate calls |
| **Coordination** | Managing work across components                          | Design handoffs like API contracts                  |
| **Artifacts**    | Semantic objects with structure and operations           | Shared state coordinates implicitly                 |
| **Autonomy**     | Self-directed operation                                  | Autonomy requires boundaries                        |
| **Evaluation**   | Measuring whether things work                            | Run evals continuously, not once                    |
| **Feedback**     | Signals that drive immediate improvement                 | Good feedback is specific and actionable            |
| **Learning**     | Accumulated improvement over time                        | Systems improve through use                         |

## Storage Structures

### Arrays

* **Access**: O(1) by index, O(n) search
* **Use for**: Conversation history, event logs, queues
* **Operations**: push, slice, filter, map

```typescript theme={null}
@field messages: Message[] = [];

// Append
this.messages.push({ role: 'user', content: input });

// Access recent
const recent = this.messages.slice(-10);

// Filter
const userMessages = this.messages.filter(m => m.role === 'user');
```

### Maps

* **Access**: O(1) by key
* **Use for**: User preferences, entity data, keyed lookup
* **Operations**: get, set, has, delete

```typescript theme={null}
@field preferences: Map<string, string> = new Map();

// Set
this.preferences.set('language', 'en');

// Get
const lang = this.preferences.get('language') || 'en';

// Check existence
if (this.preferences.has('theme')) { ... }
```

### Vector Stores

* **Access**: O(log n) approximate nearest neighbor
* **Use for**: Semantic search, knowledge bases, similar item retrieval
* **Operations**: insert, search, delete

```typescript theme={null}
@field knowledge: VectorStore<KnowledgeEntry>;

// Insert
await this.knowledge.insert({ content: 'fact', source: 'doc' });

// Search by meaning
const relevant = await this.knowledge.search(query, 5);
```

## Retrieval Patterns

| Pattern           | Implementation                 | Best For                 |
| ----------------- | ------------------------------ | ------------------------ |
| **By recency**    | `array.slice(-n)`              | Conversation context     |
| **By key**        | `map.get(key)`                 | Known identifiers        |
| **By similarity** | `vectorStore.search(query, k)` | Semantic relevance       |
| **By query**      | `array.filter(predicate)`      | Conditional access       |
| **Hybrid**        | Combine multiple patterns      | Complex context assembly |

## Flow Patterns

### Sequential

Operations that depend on each other:

```typescript theme={null}
const plan = await this.plan(task);
const result = await this.execute(plan);
const verified = await this.verify(result);
```

### Parallel

Independent operations that can run simultaneously:

```typescript theme={null}
const [research, context, history] = await Promise.all([
  this.research(topic),
  this.gatherContext(topic),
  this.loadHistory(userId)
]);
```

### Conditional

Branching based on classification or state:

```typescript theme={null}
switch (intent.category) {
  case 'faq': return this.faqHandler.handle(input);
  case 'technical': return this.techHandler.handle(input);
  default: return this.generalHandler.handle(input);
}
```

### Iterative

Loops with termination conditions:

```typescript theme={null}
while (!verification.passed && attempts < maxAttempts) {
  const revised = await this.improve(output, verification.errors);
  verification = await this.verify(revised);
  attempts++;
}
```

## Coordination Patterns

### Pipeline

Sequential handoffs through stages:

```
Ideation → Research → Draft → Edit → Review → Publish
```

### Hub and Spoke

Central coordinator delegates to specialists:

```
         ┌─── Worker A
Coordinator ─┼─── Worker B
         └─── Worker C
```

### Swarm

Peers coordinate through shared state:

```
Worker A ──┐
Worker B ──┼── Shared Artifact
Worker C ──┘
```

## Feedback Signal Types

| Signal Type            | Example                                    | Actionability                   |
| ---------------------- | ------------------------------------------ | ------------------------------- |
| **Compilation errors** | `Unexpected token at line 42`              | High—specific location          |
| **Test failures**      | `Expected 5, got 4`                        | High—expected vs actual         |
| **Type errors**        | `Type 'string' not assignable to 'number'` | High—type mismatch              |
| **Validation errors**  | `Missing required field 'email'`           | High—structural                 |
| **Quality scores**     | `Relevance: 0.7`                           | Medium—direction but not action |
| **Human feedback**     | `This doesn't address my question`         | Medium—requires interpretation  |

## Autonomy Boundaries

| Boundary Type        | Purpose                    | Implementation                     |
| -------------------- | -------------------------- | ---------------------------------- |
| **Iteration limits** | Prevent infinite loops     | `if (iterations > max) break`      |
| **Time limits**      | Bound execution duration   | `if (elapsed > timeout) abort()`   |
| **Scope limits**     | Restrict available actions | Permission levels on tools         |
| **Progress checks**  | Detect stuck states        | Compare progress across iterations |
| **Kill switches**    | Emergency halt             | External control mechanism         |

## Evaluation Dimensions

| Dimension       | Question                   | Metrics                                              |
| --------------- | -------------------------- | ---------------------------------------------------- |
| **Correctness** | Is the output right?       | Factual accuracy, task completion, format compliance |
| **Quality**     | Is the output good?        | Relevance, completeness, clarity                     |
| **Efficiency**  | What did it cost?          | Tokens, latency, API calls, dollars                  |
| **Reliability** | Does it work consistently? | Success rate, error rate, variance                   |

## Learning Types

| Type            | What's Learned           | Storage         | Application            |
| --------------- | ------------------------ | --------------- | ---------------------- |
| **Knowledge**   | Facts, information       | Vector store    | Retrieval into context |
| **Patterns**    | What works for what      | Pattern library | Strategy selection     |
| **Preferences** | User/context adaptations | User profiles   | Personalization        |
| **Skills**      | Better approaches        | Prompt variants | Generation improvement |