askexperts-coder

Convert code to RAG (Retrieval-Augmented Generation) for AI experts. This tool analyzes TypeScript projects, generates documentation for symbols, and prepares them for import into the askexperts docstore system.

Overview

askexperts-coder is a powerful tool that:

• Analyzes TypeScript projects and extracts all symbols (functions, classes, interfaces, etc.)
• Generates comprehensive documentation for each symbol using AI
• Prepares documentation in the format required for askexperts docstore import
• Supports Lightning Network payments for AI processing via NWC (Nostr Wallet Connect)

Installation

npm install -g askexperts-coder

Or install locally:

npm install askexperts-coder

Prerequisites

• Node.js (version 16 or higher)
• TypeScript project to analyze
• Lightning Network wallet with NWC support (for AI processing)
• Git repository (for tracking changes)

Complete Workflow

Here's the complete process to create an AI expert from your TypeScript codebase:

1. Analyze Symbols

First, explore your project structure and evaluate the indexer quality:

npx askexperts-coder symbols ./my-project -d

2. Generate Documentation

Generate AI-powered documentation for all symbols:

npx askexperts-coder generate ./my-project -d --nwc "nostr+walletconnect://..."

3. Prepare for Import

Convert the generated docs to docstore format:

npx askexperts-coder prepare ./my-project --dir ./prepared-docs -d

4. Create 'askexperts' user

npx askexperts user add -d

5. Create Docstore

Create a new docstore to hold your project documentation:

npx askexperts docstore create my_project_store -d

Prints docstore_id - copy it and use below.

6. Import to Docstore

Import the prepared documentation into the docstore:

npx askexperts docstore import dir ./prepared-docs -s <docstore_id> -d

7. Add wallet

npx askexperts wallet add main -n <nwc-wallet> -d

8. Create Expert

Create a RAG-enabled expert using the imported documentation and wallet:

npx askexperts expert create rag my_project_expert -d -s <docstore_id> --model gpt-4 --system_prompt "You are an expert on my TypeScript project. Use the provided documentation to answer questions accurately."

Prints expert pubkey - copy it and use below.

9. Launch RAG db

docker run -p 8000:8000 -v ./data:/data chromadb/chroma

9. Launch Expert

npx askexperts expert run <expert_pubkey> -d

10. Chat with Expert

npx askexperts expert chat <expert_pubkey> 

Commands

askexperts-coder generate <path_to_project>

Generate documentation for all symbols in a TypeScript project.

Usage:

npx askexperts-coder generate ./my-project

Options:

• -d, --debug - Enable debug output
• --nwc <string> - Lightning Node Connect (NWC) string for payment
• -n, --name - Symbol name to find if it is exported
• -c, --continue - Continue processing, skipping symbols that are already documented
• -t, --threads <number> - Number of parallel processing threads (default: 1)
• -b, --branch <string> - Expected git branch (default: main)

Description: This command analyzes your TypeScript project and generates AI-powered documentation for every symbol. It creates a .askexperts directory in your project containing JSON files with detailed documentation for each symbol.

Requirements:

• Clean git working tree
• Must be on the specified branch (default: main)
• Valid NWC string for Lightning payments

Example:

# Generate docs with debug output and 4 parallel threads
npx askexperts-coder generate ./my-project --debug --threads 4 --nwc "nostr+walletconnect://..."

# Continue interrupted generation
npx askexperts-coder generate ./my-project --continue

askexperts-coder prepare <package_path>

Convert generated documentation from the .askexperts directory to docstore format.

Usage:

npx askexperts-coder prepare ./my-project --output docs.txt

Options:

• -d, --debug - Enable debug output
• -o, --output <file> - Output file path to write combined doc content
• --dir <directory> - Directory to write individual doc files as JSON

Description: This command processes the JSON files generated by the generate command and converts them into a format suitable for RAG systems. You must specify either --output or --dir option.

Example:

# Create a single combined documentation file
npx askexperts-coder prepare ./my-project --output ./docs/combined-docs.txt

# Create individual JSON files for each symbol
npx askexperts-coder prepare ./my-project --dir ./docs/symbols/

askexperts-coder symbols <package_path>

List all symbols found in a TypeScript project.

Usage:

npx askexperts-coder symbols ./my-project

Options:

• -d, --debug - Enable debug output

Description: This command analyzes a TypeScript project and prints all discovered symbols with their locations, types, and relationships. Useful for understanding the structure of your codebase before generating documentation.

Example:

# List all symbols with debug information
npx askexperts-coder symbols ./my-project --debug

Configuration

NWC (Nostr Wallet Connect) Setup

The tool requires a Lightning Network wallet connection for AI processing payments. You can provide the NWC string in two ways:

1. Command line option: Use --nwc with any command
2. Configuration file: Create ~/.askexperts-coder.nwc file containing your NWC string

The NWC string format is typically:

nostr+walletconnect://relay-url?secret=your-secret&lud16=your-lightning-address

Project Structure

After running the generate command, your project will contain:

your-project/
├── .askexperts/
│   ├── commit.git          # Git commit hash when docs were generated
│   ├── src/
│   │   ├── file1.ts.json   # Documentation for file1.ts symbols
│   │   └── file2.ts.json   # Documentation for file2.ts symbols
│   └── ...
├── src/
│   ├── file1.ts
│   └── file2.ts
└── package.json

Examples

Complete workflow for a TypeScript project:

# 1. Explore the project structure and evaluate indexer quality
npx askexperts-coder symbols ./my-typescript-project

# 2. Generate documentation (requires NWC for payments)
npx askexperts-coder generate ./my-typescript-project --nwc "nostr+walletconnect://..."

# 3. Prepare documentation for docstore import
npx askexperts-coder prepare ./my-typescript-project --dir ./prepared-docs

# 4. Create a docstore
npx askexperts docstore create my_project_store

# 5. Import to askexperts docstore
npx askexperts docstore import dir --docstore=my_project_store --path=./prepared-docs

# 6. Create an expert
npx askexperts expert create rag my_project_expert -s my_project_store --model gpt-4 --system_prompt "Expert on my TypeScript project"

# 7. Launch the expert
npx askexperts expert run <expert_pubkey>

Resuming interrupted documentation generation:

# If generation was interrupted, continue from where it left off
npx askexperts-coder generate ./my-project --continue

High-performance documentation generation:

# Use multiple threads for faster processing
npx askexperts-coder generate ./my-project --threads 8 --debug

Creating different output formats:

# Create individual JSON files for each symbol
npx askexperts-coder prepare ./my-project --dir ./docs/symbols/

# Create a single combined documentation file
npx askexperts-coder prepare ./my-project --output ./docs/combined-docs.txt

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run start - Run the compiled CLI
• npm run dev - Run in development mode with ts-node
• npm test - Run tests (not implemented yet)

Building from source

git clone <repository-url>
cd askexperts-coder
npm install
npm run build

License

MIT

Dependencies

• askexperts - Core AI expert functionality
• commander - CLI framework
• nostr-tools - Nostr protocol implementation
• openai - OpenAI API client
• @noble/hashes - Cryptographic hashing
• debug - Debug logging utility

Troubleshooting

Common Issues

1. "No NWC string available" - Provide NWC string via --nwc option or create ~/.askexperts-coder.nwc file
2. "Git tree is not clean" - Commit or stash your changes before running generate
3. "Expected to be on branch 'main'" - Switch to the correct branch or use --branch option
4. "Project directory not found" - Ensure the path to your TypeScript project is correct

Debug Mode

Add --debug flag to any command to see detailed logging:

npx askexperts-coder generate ./my-project --debug

This will show:

• File processing progress
• Symbol analysis details
• AI processing status
• Error details and stack traces