> For the complete documentation index, see [llms.txt](https://docs.graphlit.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.graphlit.dev/api-guides/use-cases/conversations/conversation-create-and-prompt.md).

# Create and Prompt

## User Intent

"I want to create a conversation and ask questions with RAG (Retrieval Augmented Generation)"

## Operation

* **SDK Method**: `graphlit.createConversation()` + `graphlit.promptConversation()`
* **GraphQL**: `createConversation` + `promptConversation` mutations
* **Entity Type**: Conversation
* **Common Use Cases**: Q\&A over documents, chatbots, context-aware AI responses, RAG applications

## TypeScript (Canonical)

```typescript
import { Graphlit } from 'graphlit-client';
import { 
  ConversationInput,
  ConversationTypes,
  EntityState, 
  ModelServiceTypes, 
  SpecificationTypes 
} from 'graphlit-client/dist/generated/graphql-types';

const graphlit = new Graphlit();

// Step 1: Create a conversation
const conversationInput: ConversationInput = {
  name: 'Document Q&A Session',
  type: ConversationTypes.Content
};

const createResponse = await graphlit.createConversation(conversationInput);
const conversationId = createResponse.createConversation.id;

console.log(`Created conversation: ${conversationId}`);

// Step 2: Prompt the conversation (RAG query)
const promptResponse = await graphlit.promptConversation(
  'What are the key findings in the document?',  // prompt
  conversationId                                  // conversation ID
);

const answer = promptResponse.promptConversation.message.message;
console.log(`Answer: ${answer}`);

// Step 3: Continue the conversation (multi-turn)
const followUpResponse = await graphlit.promptConversation(
  'Can you provide more details about the first finding?',
  conversationId  // Same conversation for context
);

console.log(`Follow-up answer: ${followUpResponse.promptConversation.message.message}`);
```

## Parameters

### createConversation

* **`name`** (string): Display name for the conversation
* **`type`** (ConversationTypes): Conversation type
  * `CONTENT` - Q\&A over ingested content (most common)
  * `MESSAGE` - Chat-style conversations
* **`specification`** (EntityReferenceInput): Optional LLM configuration
  * Specify model (GPT-4, Claude, etc.)
  * If omitted, uses project default
* **`filter`** (ContentFilter): Optional filter to limit RAG context
  * Filter by collection, type, date, etc.
  * Only retrieve relevant content for answers

### promptConversation

* **`prompt`** (string): User's question or message
* **`id`** (string): Conversation ID (optional)
  * If provided: Continues existing conversation
  * If omitted: Creates new conversation automatically
* **`specification`** (EntityReferenceInput): Override LLM for this prompt
* **`tools`** (ToolDefinitionInput\[]): Tools for function calling (advanced)
* **`systemPrompt`** (string): Override system instructions

## Response

```typescript
// createConversation
{
  createConversation: {
    id: string;                    // Conversation ID
    name: string;                  // Conversation name
    type: ConversationTypes;       // CONTENT or MESSAGE
    state: EntityState;            // ENABLED
    specification?: Specification; // LLM configuration
  }
}

// promptConversation
{
  promptConversation: {
    messageCount: number;          // Total messages in conversation
    message: {
      message: string;             // AI's response
      role: MessageRoles.ASSISTANT; // ASSISTANT
      tokens?: number;             // Tokens used
      completionTime?: number;     // Response time (ms)
      citations?: Citation[];      // Source references (if RAG used)
    }
  }
}
```

## Developer Hints

### Conversation ID Optional in promptConversation

```typescript
// Method 1: Create conversation first (recommended for multi-turn)
const conv = await graphlit.createConversation({ name: 'Chat', type: ConversationTypes.Content });
const response = await graphlit.promptConversation('Hello', conv.createConversation.id);

// Method 2: Let promptConversation create conversation (single-turn queries)
const response = await graphlit.promptConversation('Hello');  // Creates conversation implicitly
```

**When to create conversation explicitly**:

* Multi-turn conversations (preserves context)
* Need to configure conversation (filter, specification)
* Want to manage conversation lifecycle

**When to skip explicit creation**:

* One-off questions
* Stateless API endpoints
* Quick prototyping

### RAG Context from Ingested Content

`promptConversation` automatically retrieves relevant content for answers:

```typescript
// 1. First, ingest content
await graphlit.ingestUri('https://example.com/product-docs.pdf', undefined, undefined, true);

// 2. Create conversation
const conv = await graphlit.createConversation({
  name: 'Product Support',
  type: ConversationTypes.Content
});

// 3. Ask questions - Graphlit retrieves relevant sections automatically
const response = await graphlit.promptConversation(
  'How do I reset my password?',
  conv.createConversation.id
);

// Response includes citations showing which content was used
console.log(`Answer: ${response.promptConversation.message.message}`);
console.log(`Sources: ${response.promptConversation.message.citations?.length || 0} citations`);
```

### Understanding Message Context

```typescript
// First message
const msg1 = await graphlit.promptConversation('What is machine learning?', conversationId);
console.log(msg1.promptConversation.messageCount);  // 2 (user + assistant)

// Second message (has context from first)
const msg2 = await graphlit.promptConversation('Can you give an example?', conversationId);
console.log(msg2.promptConversation.messageCount);  // 4 (user + assistant + user + assistant)

// The conversation remembers previous messages
```

### Citations for RAG Transparency

```typescript
const response = await graphlit.promptConversation(
  'What does the contract say about payment terms?',
  conversationId
);

// Check citations to see which content was used
response.promptConversation.message.citations?.forEach(citation => {
  console.log(`Source: ${citation.content?.name}`);
  console.log(`Relevance: ${citation.relevance}`);
  console.log(`Excerpt: ${citation.text}`);
});
```

## Variations

### 1. Conversation with Specific Model

Use a custom LLM specification:

```typescript
// Create specification for Claude
const specInput: SpecificationInput = {
  name: 'Claude Sonnet',
  type: SpecificationTypes.Completion,
  serviceType: ModelServiceTypes.Anthropic,
  anthropic: {
    model: AnthropicModels.Claude_3_5Sonnet
  }
};

const specResponse = await graphlit.createSpecification(specInput);

// Create conversation with specification
const convResponse = await graphlit.createConversation({
  name: 'Chat with Claude',
  type: ConversationTypes.Content,
  specification: { id: specResponse.createSpecification.id }
});

// Prompts will use Claude
const response = await graphlit.promptConversation(
  'Explain quantum computing',
  convResponse.createConversation.id
);
```

### 2. Conversation with Collection Filter

Limit RAG context to specific collections:

```typescript
// Create collection
const collectionResponse = await graphlit.createCollection({
  name: 'HR Policies'
});

// Create conversation filtered to HR collection
const convResponse = await graphlit.createConversation({
  name: 'HR Support Bot',
  type: ConversationTypes.Content,
  filter: {
    collections: [{ id: collectionResponse.createCollection.id }]
  }
});

// Questions only retrieve from HR Policies collection
const response = await graphlit.promptConversation(
  'What is the vacation policy?',
  convResponse.createConversation.id
);
// Answer based only on content in HR Policies collection
```

### 3. Multi-Turn Conversation with Context

Build context across multiple turns:

```typescript
const conv = await graphlit.createConversation({
  name: 'Data Analysis',
  type: ConversationTypes.Content
});

const convId = conv.createConversation.id;

// Turn 1
const msg1 = await graphlit.promptConversation(
  'What was our Q4 revenue?',
  convId
);
console.log(msg1.promptConversation.message.message);

// Turn 2 (references "our" from turn 1)
const msg2 = await graphlit.promptConversation(
  'How does that compare to Q3?',
  convId
);
console.log(msg2.promptConversation.message.message);

// Turn 3 (references revenue topic from turns 1-2)
const msg3 = await graphlit.promptConversation(
  'What drove the change?',
  convId
);
console.log(msg3.promptConversation.message.message);
```

### 4. Single-Turn Query (No Conversation Creation)

Quick one-off questions:

```typescript
// No conversation ID - creates one automatically
const response = await graphlit.promptConversation(
  'Summarize the key points in the uploaded documents'
);

const answer = response.promptConversation.message.message;
console.log(answer);

// Note: You lose the conversationId, can't continue later
```

### 5. Conversation with Custom System Prompt

Override default behavior:

```typescript
const response = await graphlit.promptConversation(
  'What is AI?',
  conversationId,
  undefined,  // specification
  undefined,  // mimeType
  undefined,  // data
  undefined,  // tools
  undefined,  // requireTool
  'You are a helpful assistant that explains complex topics to 5-year-olds. Use simple language and fun analogies.'  // systemPrompt
);

// Response will be in simple, child-friendly language
```

### 6. Conversation with Date Filter

Ask questions about recent content:

```typescript
const lastWeek = new Date();
lastWeek.setDate(lastWeek.getDate() - 7);

const conv = await graphlit.createConversation({
  name: 'Recent News',
  type: ConversationTypes.Content,
  filter: {
    creationDateRange: {
      from: lastWeek,
      to: new Date()
    }
  }
});

// Only retrieves from content ingested in last week
const response = await graphlit.promptConversation(
  'What are the latest developments?',
  conv.createConversation.id
);
```

## Common Issues

**Issue**: Response says "I don't have information about that"\
**Solution**: Ensure content is ingested and in FINISHED state. Check conversation filter isn't too restrictive.

**Issue**: Context from previous messages not working\
**Solution**: Verify you're using the same `conversationId` for all prompts in the conversation.

**Issue**: Getting errors about missing specification\
**Solution**: Ensure project has a default LLM configured, or explicitly provide specification when creating conversation.

**Issue**: Citations not appearing in response\
**Solution**: Citations only appear when RAG retrieves content. For pure LLM responses (no content match), there are no citations.

**Issue**: Conversation creates successfully but promptConversation fails\
**Solution**: Check that content exists and matches the conversation filter. Try prompting without filter first.

## Production Example

**Server-side conversation creation**:

```typescript
const conversationInput: ConversationInput = {
  name: userQuestion.substring(0, 80),  // First 80 chars of question
  type: ConversationTypes.Content,
  specification: specificationId ? { id: specificationId } : undefined
};

const response = await graphlit.createConversation(conversationInput, userId);
const conversationId = response.createConversation.id;
```

**One-off query pattern**:

```typescript
// Create conversation implicitly without explicit ID
const response = await graphlit.promptConversation(
  userQuestion,
  undefined,  // No conversation ID - creates new
  undefined,  // specification
  undefined,  // mimeType
  undefined,  // data
  undefined,  // tools
  undefined,  // requireTool
  undefined,  // systemPrompt
  undefined,  // includeDetails
  userId      // correlationId for tracking
);

const answer = response.promptConversation?.message?.message;
```