Ask Feature Guide

The Ask feature is a powerful RAG (Retrieval Augmented Generation) system that enables natural language conversations with your code documentation. It combines advanced retrieval techniques with AI to provide accurate, contextual answers about your codebase.

What is the Ask Feature?

The Ask feature transforms your static documentation into an interactive knowledge base where you can:

Ask natural questions about your code, APIs, and documentation
Get contextual answers with relevant code snippets and explanations
Maintain conversation history for follow-up questions
Access real-time streaming responses for immediate feedback
Query programmatically via API for integration into other tools

RAG Architecture

The Ask feature uses Retrieval Augmented Generation (RAG) to combine the best of both worlds: precise information retrieval from your docs with the natural language capabilities of large language models.

How RAG Works with Code

1. Document Indexing

When your wiki is generated, DeepWikiOpen creates semantic embeddings of your documentation:

2. Query Processing

When you ask a question, the system:

Converts your question into a semantic embedding
Searches the vector database for relevant documentation chunks
Retrieves contextual information from multiple sources
Generates a comprehensive answer using the retrieved context

// 1. Question embedding
const questionEmbedding = await embedQuery(userQuestion);

// 2. Similarity search
const relevantChunks = await vectorStore.similaritySearch(
  questionEmbedding,
  { k: 5, threshold: 0.7 }
);

// 3. Context preparation
const context = relevantChunks.map(chunk => ({
  content: chunk.content,
  source: chunk.metadata.source,
  score: chunk.score
}));

// 4. Response generation
const response = await generateResponse(userQuestion, context);

# Vector similarity search
import numpy as np
from sentence_transformers import SentenceTransformer

model = SentenceTransformer('all-MiniLM-L6-v2')

def find_relevant_docs(question, doc_embeddings, docs, top_k=5):
    question_embedding = model.encode([question])
    
    # Calculate cosine similarity
    similarities = np.dot(question_embedding, doc_embeddings.T)
    top_indices = np.argsort(similarities[0])[-top_k:][::-1]
    
    return [docs[i] for i in top_indices]

Using the Ask Interface

Basic Question Interface

The Ask feature provides an intuitive chat interface in your generated wiki:

Conversation Flow

Ask Your Question

Type your question in natural language in the Ask input field

How do I authenticate users in this API?

Real-time Processing

Watch as the system processes your query with streaming responses

Searching documentation... ⚡
Found 3 relevant sections... 📚
Generating response... 🤖

Receive Answer

Get a comprehensive answer with code examples and source references

Follow-up Questions

Continue the conversation with contextual follow-up queries

Types of Questions That Work Best

✅ Excellent Question Types

How-To Questions

Examples:

“How do I set up authentication?”
“How to handle errors in the API?”
“How do I deploy this application?”

What-Is Questions

Examples:

“What is the UserService class?”
“What does the config.json file contain?”
“What are the available endpoints?”

Code Location Questions

Examples:

“Where is the database connection configured?”
“Where are the API routes defined?”
“Which file contains the main application logic?”

Best Practice Questions

Examples:

“What’s the recommended way to handle validation?”
“Best practices for error handling?”
“How should I structure my tests?”

❌ Less Effective Question Types

These types of questions may not yield optimal results:

Vague questions without context (“How does this work?”)
Questions about code not in your documentation
Highly specific implementation details not documented
Questions requiring real-time data or external information

Example Questions and Responses

API Documentation Questions

Question
Response

User: “How do I authenticate requests to the API?”

AI: Based on your API documentation, authentication is handled using JWT tokens. Here’s how to authenticate requests:

Authentication Method

// Include the JWT token in the Authorization header
const response = await fetch('/api/users', {
  headers: {
    'Authorization': `Bearer ${jwtToken}`,
    'Content-Type': 'application/json'
  }
});

Getting a Token

First, authenticate with your credentials:

const authResponse = await fetch('/api/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    email: 'user@example.com',
    password: 'yourpassword'
  })
});

const { token } = await authResponse.json();

Sources:

/docs/api/authentication.md
/examples/auth-example.js

Code Structure Questions

Question
Response

User: “What’s the structure of the database models?”

AI: Your application uses several database models organized in the /models directory:

Core Models

// User Model
interface User {
  id: string;
  email: string;
  name: string;
  createdAt: Date;
  updatedAt: Date;
}

// Project Model  
interface Project {
  id: string;
  title: string;
  description: string;
  ownerId: string;
  members: string[];
}

Model Relationships

Sources:

/models/User.ts
/models/Project.ts
/docs/database-schema.md

Conversation History and Context

Context Retention

The Ask feature maintains conversation context throughout your session:

// Example conversation flow
const conversation = [
  {
    role: 'user',
    content: 'How do I set up the database?',
    timestamp: '2024-01-15T10:00:00Z'
  },
  {
    role: 'assistant', 
    content: 'To set up the database, you need to...',
    sources: ['/docs/setup.md', '/config/database.js'],
    timestamp: '2024-01-15T10:00:05Z'
  },
  {
    role: 'user',
    content: 'What about migrations?', // Context: Still about database setup
    timestamp: '2024-01-15T10:02:00Z'
  }
];

Follow-up Question Examples

Initial Question: API Endpoints

Q: “What API endpoints are available?”A: Lists all available endpoints with descriptions…Follow-up: “How do I use the user endpoint?” Follow-up: “What’s the rate limiting for these endpoints?” Follow-up: “Are there any authentication requirements?”

Initial Question: Error Handling

Q: “How does error handling work?”A: Explains the error handling strategy with examples…Follow-up: “What about async errors?” Follow-up: “How do I log these errors?” Follow-up: “Are there custom error types?”

Streaming Responses and Real-time Interaction

Streaming Implementation

The Ask feature provides real-time streaming responses for immediate feedback:

const askQuestion = async (question: string) => {
  const response = await fetch('/api/ask', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ question })
  });

  const reader = response.body?.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        updateUI(data); // Real-time UI updates
      }
    }
  }
};

from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import json

app = FastAPI()

@app.post("/api/ask")
async def ask_question(question: dict):
    def generate_response():
        # Search for relevant documents
        yield f"data: {json.dumps({'type': 'status', 'message': 'Searching...'})}\n\n"
        
        relevant_docs = search_documents(question['question'])
        yield f"data: {json.dumps({'type': 'status', 'message': f'Found {len(relevant_docs)} relevant sections'})}\n\n"
        
        # Generate streaming response
        for chunk in generate_answer(question['question'], relevant_docs):
            yield f"data: {json.dumps({'type': 'content', 'chunk': chunk})}\n\n"
        
        yield f"data: {json.dumps({'type': 'complete'})}\n\n"
    
    return StreamingResponse(generate_response(), media_type="text/plain")

Visual Feedback

The interface provides visual indicators for:

Search progress with animated loading states
Token-by-token streaming for real-time response building
Source highlighting as references are found
Completion status when the response is finished

API Usage for Programmatic Q&A

REST API Endpoints

curl -X POST "https://your-wiki.com/api/ask" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "question": "How do I implement user authentication?",
    "conversation_id": "conv_123",
    "include_sources": true,
    "stream": false
  }'

import { DeepWikiClient } from '@deepwiki/client';

const client = new DeepWikiClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://your-wiki.com'
});

// Simple question
const response = await client.ask({
  question: "How do I set up the development environment?",
  includeSource: true
});

console.log(response.answer);
console.log(response.sources);

// Streaming question
const stream = client.askStreaming({
  question: "Explain the authentication flow",
  conversationId: "conv_123"
});

for await (const chunk of stream) {
  if (chunk.type === 'content') {
    process.stdout.write(chunk.text);
  }
}

from deepwiki import DeepWikiClient

client = DeepWikiClient(
    api_key="your-api-key",
    base_url="https://your-wiki.com"
)

# Synchronous question
response = client.ask(
    question="What are the available API endpoints?",
    include_sources=True
)

print(response.answer)
for source in response.sources:
    print(f"Source: {source.file} (Score: {source.relevance_score})")

# Asynchronous streaming
async for chunk in client.ask_streaming(
    question="How does error handling work?",
    conversation_id="conv_456"
):
    if chunk.type == "content":
        print(chunk.text, end="", flush=True)

API Response Format

{
  "id": "ask_123456789",
  "question": "How do I authenticate users?",
  "answer": "To authenticate users in this API, you use JWT tokens...",
  "sources": [
    {
      "file": "/docs/authentication.md",
      "title": "Authentication Guide", 
      "relevance_score": 0.95,
      "excerpt": "JWT tokens are used for authentication..."
    },
    {
      "file": "/examples/auth.js",
      "title": "Authentication Example",
      "relevance_score": 0.87,
      "excerpt": "const token = jwt.sign(payload, secret);"
    }
  ],
  "conversation_id": "conv_123",
  "timestamp": "2024-01-15T10:30:00Z",
  "processing_time_ms": 1250
}

Best Practices for Effective Questions

🎯 Writing Better Questions

Be Specific

Instead of: “How does this work?”Try: “How does user authentication work in the login endpoint?”

Provide Context

Instead of: “Fix this error”Try: “How do I handle the ‘Database connection failed’ error when starting the server?”

Ask About Documented Features

Good: “What configuration options are available for the email service?”Less Good: “How do I integrate with an undocumented third-party service?”

Use Examples

Better: “How do I format a POST request to create a new user with email and password fields?”vs: “How do I create users?”

📝 Question Templates

How-To Template
What-Is Template
Where-Find Template
Best-Practice Template

How do I [specific action] in [specific context]?

Examples:
- How do I configure Redis caching in the production environment?
- How do I validate user input in the registration form?
- How do I set up database migrations for the User model?

What is [specific component/concept] and how does it [function/relate]?

Examples:
- What is the AuthMiddleware class and how does it validate tokens?
- What is the config.database object and how does it connect to PostgreSQL?
- What is the UserService and how does it interact with the database?

Where can I find [specific functionality/configuration] for [context]?

Examples:
- Where can I find the API rate limiting configuration?
- Where are the email templates stored for password reset?
- Where is the logging configuration for production deployment?

What's the recommended way to [specific task] in this codebase?

Examples:
- What's the recommended way to handle async errors in API endpoints?
- What's the recommended way to structure test files for components?
- What's the recommended way to manage environment variables?

💡 Advanced Query Techniques

Multi-part Questions

Break complex questions into parts:Instead of: “How do I set up the database, configure authentication, and deploy to production?”Try:

“How do I set up the database for development?”
“How do I configure JWT authentication?” (follow-up)
“What’s the deployment process for production?” (follow-up)

Reference Previous Context

Build on previous answers:After asking about authentication:

“How do I test these authentication endpoints?”
“What error codes does this authentication return?”
“How do I refresh expired tokens mentioned earlier?”

Ask for Examples

Request concrete examples:Good questions:

“Can you show me an example of making a POST request to create a user?”
“What does a typical error response look like?”
“Can you provide a sample configuration file?”

Limitations and Troubleshooting

Known Limitations

Current limitations of the Ask feature:

Documentation Scope: Only searches indexed documentation and code files
Real-time Data: Cannot access live databases or external APIs
Code Execution: Cannot run or test code, only explain existing code
Version Specificity: May not distinguish between different versions of your code
Complex Logic: May struggle with highly complex business logic without clear documentation

Common Issues and Solutions

No Relevant Results Found

Symptoms: The AI responds with “I couldn’t find relevant information”Solutions:

Check if your question relates to documented features
Try rephrasing with different terminology
Ensure your documentation was properly indexed
Ask more specific questions about documented components

Example Fix:

❌ “How do I use advanced features?”
✅ “How do I configure the email notification system?”

Inaccurate or Incomplete Answers

Symptoms: The response doesn’t match your actual codebaseSolutions:

Verify your documentation is up-to-date
Re-index your documentation if you’ve made recent changes
Provide more context in your question
Ask follow-up questions for clarification

Example:

Q: "The authentication process you described doesn't match my code"
Follow-up: "Can you show me specifically how JWT tokens are validated in the middleware?"

Slow Response Times

Symptoms: Questions take a long time to processSolutions:

Check if you’re asking very broad questions (try being more specific)
Verify your internet connection for streaming responses
Consider if your documentation is very large (may require longer processing)
Use the API with appropriate timeout settings

Optimization:

// Set appropriate timeouts for API calls
const response = await client.ask({
  question: "How do I configure logging?",
  timeout: 30000 // 30 seconds
});

Context Not Maintained

Symptoms: Follow-up questions don’t reference previous conversationSolutions:

Ensure you’re using the same conversation session
Check that cookies/session storage is enabled
For API usage, pass the same conversation_id
Start a new conversation if context becomes confusing

API Example:

// Maintain conversation context
const conversationId = 'conv_' + Date.now();

const response1 = await client.ask({
  question: "How do I set up authentication?",
  conversationId
});

const response2 = await client.ask({
  question: "What about authorization for these endpoints?",
  conversationId // Same ID maintains context
});

Performance Optimization Tips

Question Optimization
API Usage
Conversation Management

Optimize your questions for better performance:

✅ Good Performance:
- Specific questions about documented features
- Questions referencing specific file names or classes
- Well-structured questions with clear context

❌ Poor Performance:  
- Extremely broad questions requiring full codebase analysis
- Questions about undocumented or external dependencies
- Vague questions without specific context

Optimize API calls:

// Use appropriate parameters
const response = await client.ask({
  question: "How do I configure the database?",
  maxSources: 3,        // Limit sources for faster processing
  includeSourceText: false, // Skip full source text if not needed
  stream: true          // Use streaming for better perceived performance
});

Manage conversations efficiently:

// Clear conversation context when changing topics
if (isNewTopic(question)) {
  conversationId = generateNewConversationId();
}

// Archive old conversations to improve performance
if (conversationAge > MAX_CONVERSATION_AGE) {
  await client.archiveConversation(conversationId);
  conversationId = generateNewConversationId();
}

Debug Mode

Enable debug mode to troubleshoot issues:

const client = new DeepWikiClient({
  apiKey: 'your-api-key',
  debug: true  // Enables detailed logging
});

const response = await client.ask({
  question: "How does caching work?",
  debug: true  // Request debug information
});

console.log('Debug Info:', response.debug);
// Shows: query processing time, sources found, embedding similarity scores

client = DeepWikiClient(
    api_key="your-api-key",
    debug=True
)

response = client.ask(
    question="How does error handling work?",
    debug=True
)

print("Sources found:", len(response.sources))
print("Processing time:", response.processing_time_ms)
print("Query embedding dimensions:", response.debug.embedding_dimensions)

Need Help?

Still having issues?

Check the API Documentation for detailed endpoint information
Review Common Patterns for question examples
Contact support with specific error messages and question examples
Join our community Discord for real-time help

Next Steps

API Reference

Detailed API documentation for programmatic access

Integration Guide

Learn how to integrate Ask into your applications

Advanced Features

Explore advanced Ask feature capabilities

Best Practices

Tips and patterns for effective documentation Q&A

​Ask Feature Guide

​What is the Ask Feature?

RAG Architecture

​How RAG Works with Code

​1. Document Indexing

​2. Query Processing

​Using the Ask Interface

​Basic Question Interface

​Conversation Flow

​Types of Questions That Work Best

​✅ Excellent Question Types

How-To Questions

What-Is Questions

Code Location Questions

Best Practice Questions

​❌ Less Effective Question Types

​Example Questions and Responses

​API Documentation Questions

​Authentication Method

​Getting a Token

​Code Structure Questions

​Core Models

​Model Relationships

​Conversation History and Context

​Context Retention

​Follow-up Question Examples

​Streaming Responses and Real-time Interaction

​Streaming Implementation

​Visual Feedback

​API Usage for Programmatic Q&A

​REST API Endpoints

​API Response Format

​Best Practices for Effective Questions

​🎯 Writing Better Questions

Be Specific

Provide Context

Ask About Documented Features

Use Examples

​📝 Question Templates

​💡 Advanced Query Techniques

​Limitations and Troubleshooting

​Known Limitations

​Common Issues and Solutions

​Performance Optimization Tips

​Debug Mode

Need Help?

​Next Steps

API Reference

Integration Guide

Advanced Features

Best Practices

Ask Feature Guide

What is the Ask Feature?

How RAG Works with Code

1. Document Indexing

2. Query Processing

Using the Ask Interface

Basic Question Interface

Conversation Flow

Types of Questions That Work Best

✅ Excellent Question Types

❌ Less Effective Question Types

Example Questions and Responses

API Documentation Questions

Authentication Method

Getting a Token

Code Structure Questions

Core Models

Model Relationships

Conversation History and Context

Context Retention

Follow-up Question Examples

Streaming Responses and Real-time Interaction

Streaming Implementation

Visual Feedback

API Usage for Programmatic Q&A

REST API Endpoints

API Response Format

Best Practices for Effective Questions

🎯 Writing Better Questions

📝 Question Templates

💡 Advanced Query Techniques

Limitations and Troubleshooting

Known Limitations

Common Issues and Solutions

Performance Optimization Tips

Debug Mode

Next Steps