npm package: @qingtingnpm/q-chat-ollama
Description: A chat application using Ollama API with qwen3:8b model
Author: qingtingnpm
Latest version: 1.0.3

# Q-Chat

A powerful chat application built with Node.js, using Ollama API and the qwen3:8b model. This npm package provides a complete chat interface with modern UI and extensible architecture.

## Features

- 🚀 **Real-time Chat**: Interactive chat interface with AI assistant
- 🤖 **Multiple Models**: Support for various Ollama models (qwen3:8b, mistral:7b, etc.)
- 📝 **Markdown Support**: Rich text rendering with code highlighting
- 🎨 **Modern UI**: Dark theme with responsive design
- 🔧 **Debug Mode**: Built-in debugging capabilities
- 📱 **Responsive**: Works on desktop and mobile devices
- 🛠️ **v1.0.3 Fixes**: 
  - Fixed model list display issues (no more undefined)
  - Improved JSON handling for different environments
  - Enhanced error handling and debugging output
  - Fixed static file serving in development mode

## Quick Start

### Prerequisites

- Node.js (>=14.0.0)
- Ollama installed and running (optional, uses mock data by default)

### Installation

```bash
npm install q-chat
```

### Basic Usage

```javascript
const { startServer } = require('q-chat');

// Start the server
startServer({
    port: 3000,
    debug: true  // Enable debug mode
});
```

### Development Mode

```bash
# Clone the repository
git clone <repository-url>
cd q-chat

# Install dependencies
npm install

# Start development server (backend + frontend)
npm run dev

# Access the application
# Frontend: http://localhost:5173
# Backend API: http://localhost:3000/api
```

## API Documentation

### Core Endpoints

#### GET `/api/models`
Returns available Ollama models.

**Response:**
```json
{
    "success": true,
    "data": [
        {
            "name": "qwen3:8b",
            "size": "7B",
            "modified": "2023-11-01"
        }
    ]
}
```

#### POST `/api/chat`
Send a chat message to the AI model.

**Request Body:**
```json
{
    "message": "Hello, how are you?",
    "model": "qwen3:8b"
}
```

**Response:**
```json
{
    "success": true,
    "data": {
        "id": 1234567890,
        "role": "assistant",
        "content": "I'm doing well, thank you!",
        "timestamp": "2023-11-05T10:30:00.000Z",
        "model": "qwen3:8b"
    },
    "history": [...]
}
```

#### GET `/api/history`
Get chat history.

#### DELETE `/api/history`
Clear chat history.

### Extension Endpoints

#### GET `/api/tree/connect`
Directory tree integration interface.

#### GET `/api/editor/connect`
Code editor integration interface.

#### GET `/api/mcp/connect`
MCP (Model Context Protocol) integration interface.

## Development

### Project Structure

```
q-chat/
├── src/
│   ├── backend/
│   │   └── server.js          # Main server file
│   └── frontend/
│       ├── index.html         # Main HTML file
│       ├── styles.css         # CSS styles
│       └── script.js          # Frontend JavaScript
├── test/
│   ├── server.test.js         # Backend tests
│   └── frontend.test.js       # Frontend tests
├── dist/                      # Build output
├── package.json
└── README.md
```

### Scripts

```bash
# Development
npm run dev              # Start both backend and frontend
npm run dev:backend      # Start backend only
npm run dev:frontend     # Start frontend only

# Build
npm run build            # Build both backend and frontend
npm run build:backend    # Build backend only
npm run build:frontend   # Build frontend only

# Testing
npm test                 # Run all tests
npm run test:watch       # Run tests in watch mode

# Linting
npm run lint             # Run ESLint

# Preview
npm run preview          # Preview built application
```

### Debug Mode

Enable debug mode to see detailed logs:

```bash
# Environment variable
DEBUG=true npm run dev

# Command line flag
npm run dev -- --debug

# URL parameter (frontend)
http://localhost:5173?debug=true
```

## Extensibility

### Directory Tree Integration

To integrate a directory tree component:

1. Call `/api/tree/connect` for available methods
2. Implement tree rendering component
3. Handle expand/collapse operations

### Code Editor Integration

To integrate a code editor:

1. Call `/api/editor/connect` for available methods
2. Integrate Monaco Editor or CodeMirror
3. Implement file operations

### MCP Integration

To integrate MCP tools:

1. Call `/api/mcp/connect` for available methods
2. Implement tool execution interface
3. Handle tool registration and execution

## Testing

Run the test suite:

```bash
npm test
```

Test coverage includes:
- Backend API endpoints
- Frontend functionality (simulated)
- Error handling
- Edge cases

## Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Create an issue on GitHub
- Check the documentation
- Enable debug mode for troubleshooting

## Changelog

### v1.0.0
- Initial release
- Basic chat functionality
- Mock Ollama integration
- Modern UI with dark theme
- Markdown support
- Debug mode
- Test suite