Skip to content

README.md

Latest commit

 

History

History
211 lines (166 loc) · 6.71 KB

README.md

File metadata and controls

211 lines (166 loc) · 6.71 KB

ScripturaAI

Python Next.js Flask

An intelligent documentation generation platform that leverages AI to automatically create comprehensive documentation, docstrings, algorithm explanations, guides, and visual diagrams from your codebase.

Features

Core Capabilities

  • Smart Docstring Generation: Automatically generate professional docstrings/documentation for your code
  • Algorithm Explanation: Convert complex code into clear, step-by-step algorithm explanations
  • Guide Creation: Generate comprehensive guides and tutorials from your codebase
  • Mermaid Diagrams: Create visual flowcharts and diagrams to illustrate code logic
  • GitHub Integration: Clone and process entire repositories for documentation
  • Web Interface: Beautiful, modern web interface for easy interaction
  • VS Code Extension: Generate documentation directly from your editor with Ctrl+D

Multiple Input Methods

  • Single Code Input: Paste code directly into the web interface
  • File Upload: Upload multiple code files for batch processing
  • GitHub Repository: Process entire repositories by providing a GitHub URL
  • VS Code Integration: Generate documentation without leaving your editor

Output Formats

  • Enhanced Code: Original code with added docstrings and comments
  • Markdown Documentation: Professional documentation in Markdown format
  • Algorithm Explanations: Step-by-step breakdowns of code logic
  • Mermaid Diagrams: Visual representations of code flow
  • MkDocs Integration: Generate static documentation websites

Architecture

ScripturaAI consists of three main components:

                    ┌─────────────────────┐
                    │      Frontend       │
                    │      (Next.js)      │
                    └──────────┬──────────┘
                               │
                               │ HTTP/REST
                               │
                    ┌──────────▼──────────┐
                    │      Backend        │
                    │    (Flask API)      │
                    └─────────┬───────────┘
                              │
                              │ API Calls
                              │
                    ┌─────────▼───────────┐
                    │    AI Engine        │
                    │  (OpenAI/LangChain) │
                    └─────────────────────┘

    Additional Components:
    
    ┌─────────────┐    ┌─────────────┐    ┌─────────────┐
    │  VS Code    │    │   GitHub    │    │   MkDocs    │
    │ Extension   │───►│ Integration │───►│  Generator  │
    └─────────────┘    └─────────────┘    └─────────────┘
           │                   │                   │
           └───────────────────┼───────────────────┘
                               │
                        ┌──────▼──────┐
                        │   Backend   │
                        │ (Flask API) │
                        └─────────────┘

Technology Stack

Frontend:

  • Next.js 15 with TypeScript
  • Tailwind CSS for modern UI
  • Radix UI components
  • Monaco Editor for code editing
  • Dark/Light theme support

Backend:

  • Python 3.12+ with Flask
  • LangChain for AI orchestration
  • OpenAI GPT-4 for code analysis
  • File processing and Git integration
  • MkDocs for documentation generation

VS Code Extension:

  • JavaScript-based extension
  • Keyboard shortcuts (Ctrl+D)
  • Real-time integration with backend

Getting Started

Prerequisites

  • Python 3.12+
  • Node.js 18+
  • pnpm (recommended) or npm
  • OpenAI API Key

1. Clone the Repository

git clone https://github.com/Team-Hacksmith/ScripturaAI.git
cd ScripturaAI

2. Backend Setup

cd backend

# Install dependencies using Poetry
pip install poetry
poetry install

# Or use pip
pip install -r requirements.txt

# Set up environment variables
cp .env.example .env
# Edit .env and add your OpenAI API key

3. Frontend Setup

cd frontend

# Install dependencies
pnpm install
# or npm install

# Start development server
pnpm dev
# or npm run dev

4. VS Code Extension Setup

cd hacksmith-vsce

# Install dependencies
pnpm install

# Package the extension (optional)
npx vsce package

5. Environment Configuration

Create a .env file in the backend directory:

OPENAI_API_KEY=your_openai_api_key_here

Usage

Web Interface

  1. Start the Backend:

    cd backend
poetry run python main.py
# or python main.py

  2. Start the Frontend:

    cd frontend
pnpm dev

  3. Open your browser to http://localhost:3000

Available Generation Types

Code Documentation

  • Adds professional docstrings to functions and classes
  • Supports Python, JavaScript, C/C++, and more
  • Preserves original code structure

Algorithm Explanation

  • Converts code into step-by-step explanations
  • Perfect for educational content
  • Outputs in Markdown format

Guide Generation

  • Creates comprehensive tutorials
  • Explains code purpose and usage
  • Ideal for project documentation

Diagram Creation

  • Generates Mermaid flowcharts
  • Visualizes code logic and flow
  • Great for architecture documentation

VS Code Extension

  1. Install the extension from the hacksmith-vsce folder
  2. Select code in VS Code
  3. Press Ctrl+D or run "hacksmith" command
  4. Get AI-generated documentation instantly

API Endpoints

POST /upload          # Upload files for processing
POST /single          # Process single code snippet
POST /github/clone    # Clone and process GitHub repository
POST /github/docs     # Generate documentation website
GET  /docs/{repo}     # Access generated documentation