# 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;
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.graphlit.dev/api-guides/use-cases/conversations/conversation-create-and-prompt.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.