Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (ai-documenter) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

AI Documenter

AI Documenter is an AI-powered technical documentation assistant designed to analyze codebases, files, and directories, generating accurate, well-structured documentation, README files, API docs, and technical guides. It supports both OpenAI models (cloud) and LMStudio (local) for deep code and documentation analysis, making it an ideal tool for developers and technical writers who value flexibility and privacy.

Features

Interactive CLI: Engage in natural conversations with the documentation assistant via a terminal-based interface.
Multiple AI Providers: Choose between OpenAI (cloud) or LMStudio (local) for AI processing.
Automated Documentation: Generate documentation for source files, project directories, configuration files, and more.
Inline Documentation: Add technical documentation directly inside source files (JSDoc, docstrings, etc.) using language-specific standards.
AI-Powered Analysis: Integrates OpenAI's latest models or local LMStudio models for advanced understanding and generation.
Privacy-First Option: Use LMStudio for completely local processing without sending code to external APIs.
Multi-Language Support: Supports documentation standards for JavaScript/TypeScript, Python, Java, C#, Go, Rust, PHP, and Ruby.
Customizable Tools: File system read/write, directory and file info, project structure analysis, and more.
Project-Specific Configuration: Configurable per-project with .documenter.json config files.
Global Installation: Install once, use anywhere in your projects.
Built-in Help & Guidance: Easily accessible help and usage examples within the CLI.

Installation

Global Installation (Recommended)

Install AI Documenter globally to use it in any project:

npm install -g ai-documenter

Local Installation

Install in a specific project:

npm install ai-documenter
npx ai-documenter

From Source

Clone the Repository:

git clone <repository-url>
cd documenter

Install Dependencies:
```
npm install
```

Build and Install:

npm run build
npm link  # For global installation

Quick Start

Initialize AI Documenter in your project:
```
cd your-project
ai-documenter init
```
Start the documentation assistant:
```
ai-documenter
```
Start documenting! Try commands like:
- "Document the file src/app.js"
- "Create a README for this project"
- "Explain the src/ folder structure"

Configuration

AI Documenter supports both OpenAI (cloud) and LMStudio (local) providers for maximum flexibility.

Environment Variables

Common Settings

LLM_PROVIDER (Optional): Choose provider: openai or lmstudio (default: openai)
MAX_CONVERSATION_HISTORY (Optional): Number of conversation turns to remember (default: 10)
DEFAULT_OUTPUT_DIR (Optional): Default directory for generated documentation (default: ./docs)
LLM_TIMEOUT (Optional): Request timeout in milliseconds (default: 3600000)

OpenAI Provider

OPENAI_API_KEY (Required for OpenAI): Your OpenAI API key
OPENAI_MODEL (Optional): Model to use (default: gpt-4o-mini)

LMStudio Provider

LMSTUDIO_ENDPOINT (Optional): LMStudio API endpoint (default: http://localhost:1234/v1)
LMSTUDIO_MODEL (Optional): Model name in LMStudio (default: local-model)

Configuration File

Create a .documenter.json file in your project root (this file is automatically added to .gitignore):

OpenAI Configuration

{
  "provider": "openai",
  "openai_api_key": "your-api-key-here",
  "openai_model": "gpt-4o-mini",
  "max_conversation_history": 10,
  "default_output_dir": "./docs"
}

LMStudio Configuration

{
  "provider": "lmstudio",
  "lmstudio_endpoint": "http://localhost:1234/v1",
  "lmstudio_model": "your-local-model-name",
  "max_conversation_history": 10,
  "default_output_dir": "./docs"
}

Configuration Priority

.documenter.json in current directory
documenter.config.json in current directory
Environment variables
.env file in current directory
Global .env file in ~/.documenter/.env

Note: Configuration files (.documenter.json, documenter.config.json) are automatically excluded from git to prevent committing sensitive API keys. For team projects, document the required configuration in your project's README instead of committing the actual config files.

LMStudio Setup

To use LMStudio for local AI models:

Download and Install LMStudio from https://lmstudio.ai
Download a Model (e.g., Code Llama, Mistral, or other coding-focused models)
Start the Local Server in LMStudio (typically runs on port 1234)

Configure AI Documenter:

ai-documenter init
# Select option 2 for LMStudio when prompted

Set Environment Variables (optional):

export LLM_PROVIDER=lmstudio
export LMSTUDIO_ENDPOINT=http://localhost:1234/v1
export LMSTUDIO_MODEL=your-model-name

Benefits of LMStudio:

✅ Complete privacy - your code never leaves your machine
✅ No API costs - run unlimited documentation generation
✅ Works offline - no internet connection required
✅ Custom models - use specialized coding models

Usage

Interactive Mode

Run ai-documenter to start the interactive documentation assistant:

ai-documenter

Initialize a Project

Set up AI Documenter configuration for your project:

ai-documenter init

Example Commands

Once in interactive mode, try these commands:

External Documentation:

Document the file src/app.js
Explain the src/ folder structure
Write API docs for this project
Create a README for this project
Explain how this code works
Generate documentation for the entire codebase

Inline Documentation:

Add JSDoc comments to src/utils.js
Add docstrings to all functions in models.py
Document the UserService class with proper JSDoc
Add inline documentation to utils/helpers.ts
Document all methods in the PaymentProcessor class
Add Python docstrings following PEP 257 standards

CLI Commands

exit or quit - Exit the application
clear - Reset conversation and clear the screen
help - Display help message
init - Initialize documenter in current directory

Inline Documentation

AI Documenter now supports writing technical documentation directly inside your source files using industry-standard formats for each programming language.

Supported Languages & Standards

JavaScript/TypeScript: JSDoc format with @param, @returns, @throws, @example tags
Python: PEP 257 compliant docstrings with Args, Returns, Raises, Examples sections
Java: JavaDoc format with @param, @return, @throws, @since tags
C#: XML documentation with <summary>, <param>, <returns>, <exception> tags
Go: Standard Go documentation comments
Rust: Documentation comments with /// syntax
PHP: PHPDoc standards with /** */ comments
Ruby: YARD documentation format

How It Works

Analyze: The AI reads your source files to understand function signatures, parameters, and behavior
Generate: Creates appropriate inline documentation using language-specific standards
Preserve: Maintains existing code logic and formatting while adding documentation
Update: Uses the write_file tool to update your source files with enhanced documentation

Example Usage

# Add JSDoc comments to a JavaScript file
"Add JSDoc comments to src/api/userService.js"

# Document Python functions with proper docstrings
"Add docstrings to all functions in data/models.py"

# Document a specific class
"Document the PaymentProcessor class with comprehensive JSDoc"

# Bulk documentation for a file
"Add inline documentation to utils/helpers.ts following TypeScript standards"

What Gets Documented

Functions/Methods: Parameters, return values, exceptions, usage examples
Classes: Purpose, constructor parameters, public methods, properties
Interfaces/Types: Property descriptions and usage patterns
Modules: Overall purpose, exports, and important usage notes
Complex Logic: Step-by-step explanations for algorithms and business logic

Project Structure

ai-documenter/
├── src/
│   ├── main.ts                    # Main CLI application and entry point
│   ├── types.ts                   # TypeScript type definitions
│   ├── classes/                   # Core application classes
│   │   ├── agent.ts               # Custom agent implementation for multiple providers
│   │   ├── animation.ts           # CLI loading animations and visual effects
│   │   ├── cache.ts               # Caching utilities and management
│   │   ├── cli.ts                 # CLI interface management and command handling
│   │   ├── config.ts              # Configuration management and validation
│   │   ├── display.ts             # Terminal display utilities and formatting
│   │   ├── errors.ts              # Error handling and custom error types
│   │   └── history.ts             # Conversation history management
│   ├── helpers/                   # Utility helper functions
│   │   ├── conversation.ts        # Conversation management utilities
│   │   ├── file-operations.ts     # File system operations and utilities
│   │   ├── init.ts                # Project initialization and setup
│   │   └── validation.ts          # Input validation and sanitization
│   ├── llm/                       # AI/LLM provider integration
│   │   ├── prompt.ts              # Agent instructions and prompt templates
│   │   └── providers.ts           # Provider abstraction (OpenAI, LMStudio)
│   └── tools/                     # File and directory tools used by the agent
│       ├── index.ts               # Tool exports and registration
│       ├── analyze-project.ts     # Project structure analysis
│       ├── fuzzy-find-files.ts    # Fuzzy file search functionality
│       ├── get-file-info.ts       # File information retrieval
│       ├── list-directory.ts      # Directory listing tool
│       ├── read-file.ts           # File reading tool
│       ├── search-file-content.ts # Content search within files
│       ├── search-files.ts        # File search by name/pattern
│       └── write-file.ts          # File writing tool
├── bin/                           # Built executable (generated)
├── package.json                   # Project configuration and dependencies
├── tsconfig.json                  # TypeScript configuration
└── README.md                      # This file

Configuration Examples

Basic Setup

Global API Key (works everywhere):

echo "OPENAI_API_KEY=your-key-here" >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc

Project-Specific Setup:

cd your-project
ai-documenter init
# Follow the prompts to configure

Advanced Configuration

Create .documenter.json for project-specific settings:

{
  "openai_model": "gpt-4o",
  "default_output_dir": "./documentation",
  "max_conversation_history": 20
}

Development

Running from Source

npm run dev

Building

npm run build
./bin/ai-documenter

Publishing

npm run build
npm publish

Customization

Edit src/prompt.ts to change instructions for the technical writer agent
Enhance src/tools.ts to extend or modify file system tools
Modify src/main.ts to add new commands or change behavior
Customize src/display.ts to modify terminal output formatting and styling
Extend src/cli.ts to add new CLI features and command handling

Use Cases

API Documentation: Generate comprehensive API docs from source code
README Files: Create project overviews and setup instructions
Code Explanations: Understand and document complex codebases
Technical Guides: Create step-by-step implementation guides
Architecture Documentation: Document system design and structure
Configuration Documentation: Explain config files and settings
Inline Code Documentation: Add JSDoc, docstrings, and comments directly to source files
Legacy Code Documentation: Document existing codebases that lack proper inline documentation
Team Onboarding: Ensure consistent documentation standards across development teams

Tips

Use specific file paths for targeted documentation
Ask for explanations of code patterns and architecture
Request documentation in specific formats (Markdown, HTML, etc.)
Combine multiple requests in conversation for comprehensive docs
Use the clear command to start fresh documentation sessions
For inline documentation: Specify the documentation standard you prefer (e.g., "JSDoc", "PEP 257")
Batch documentation: Ask to document multiple files at once for consistency
Review changes: Always review generated inline documentation before committing to ensure accuracy

Troubleshooting

API Key Issues

If you get an API key error:

Run ai-documenter init to set up configuration
Check environment variables: echo $OPENAI_API_KEY
Verify .env file exists in your project or home directory
Check .documenter.json configuration file

Permission Issues

If you get permission errors:

# Fix npm permissions
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH

Build Issues

If the build fails:

# Clean and rebuild
rm -rf bin/
npm run build

Contributing

Pull requests, bug reports, and feature suggestions are welcome! Please open an issue for discussion before making major changes.

License

MIT License