--- title: Naexya Docs AI emoji: 📋 colorFrom: blue colorTo: purple sdk: gradio sdk_version: "4.0.0" app_file: app.py pinned: false --- # Naexya Docs AI Open-source AI-powered specification management tool that helps product and engineering teams collaborate with multiple large language models, extract structured requirements, and export professional documentation without leaving a browser tab. --- ## Features - **Multi-provider AI integration** (OpenAI, Anthropic, Google, xAI, Moonshot, Qwen) with a unified client and per-provider rate limit awareness. - **Dual AI personas** (Requirements Specialist + Technical Architect) designed to capture business context and technical design details in parallel. - **Conversation-based specification extraction** that promotes iterative refinement and transparent traceability back to the originating chat history. - **Validation workflow for quality control** so human reviewers can approve or reject generated specifications before they become canonical. - **Professional export to HTML/Markdown** leveraging branded templates optimised for stakeholders and AI coding agents alike. - **Local SQLite storage (no cloud dependencies)** providing self-hosted data retention with optional demo seed data for evaluation. - **Bring-your-own-API-key model** ensuring you retain full control over model usage, quotas, and billing across all supported vendors. --- ## Quick Start 1. **Clone the repository** ```bash git clone https://github.com/your-org/NaexyaDocsAI.git cd NaexyaDocsAI ``` 2. **Create an isolated environment (recommended)** ```bash python3 -m venv .venv source .venv/bin/activate # Windows: .venv\\Scripts\\activate ``` 3. **Install dependencies** ```bash pip install --upgrade pip pip install -r requirements.txt ``` 4. **Copy environment template and add your API keys** ```bash cp .env.example .env # Edit .env with your provider keys ``` 5. **Launch the Gradio application** ```bash python app.py ``` 6. **Open the local URL** printed by Gradio (typically `http://127.0.0.1:7860/`) to start collaborating with the personas and managing specifications. > 💡 **Tip:** If you do not yet have API keys, enable the built-in demo data from the landing page. This allows you to explore the interface, validation queue, and export flows without making external API calls. --- ## Configuration The platform is fully configurable through `config.py` and environment variables loaded from `.env`. Each provider entry defines endpoints, default parameters, and header templates to help you stay within rate limits. ### Environment Variables | Variable | Description | | --- | --- | | `OPENAI_API_KEY` | Secret key for OpenAI GPT-5 endpoints. | | `ANTHROPIC_API_KEY` | Authentication token for Claude models. | | `GOOGLE_API_KEY` | Google AI Studio API key for Gemini models. | | `XAI_API_KEY` | API key for xAI Grok models. | | `MOONSHOT_API_KEY` | Credential for Moonshot (Kimi) access. | | `QWEN_API_KEY` | Access token for Alibaba Qwen models. | > ⚠️ Keep the `.env` file out of version control. Only `.env.example` should be committed. ### Provider Setup Details 1. **OpenAI (GPT-5)** - Create or reuse an OpenAI account and generate a key from the dashboard. - Ensure the `https://api.openai.com/v1/chat/completions` endpoint is enabled for your organisation. - Optional parameters such as `temperature` and `max_tokens` can be fine-tuned in `config.py`. 2. **Anthropic (Claude-4-Sonnet)** - Request access to Claude-4 via the Anthropic console. - Place the key in `.env` as `ANTHROPIC_API_KEY`. - Respect the token per-minute limits published in the console; the defaults in `config.py` reflect conservative usage. 3. **Google (Gemini-2.5-Pro)** - Enable the Generative Language API in Google Cloud and create credentials through Google AI Studio. - Set `GOOGLE_API_KEY` and confirm the project has the `models.generateContent` permission. 4. **xAI (Grok-4-Fast)** - Obtain access from the xAI developer portal and generate an API key. - Update `.env` with `XAI_API_KEY`; the client automatically adds the `x-api-key` header required by Grok. 5. **Moonshot (Kimi-K2)** - Sign in to Moonshot AI, subscribe to the Kimi API plan, and generate a token. - Store the token in `MOONSHOT_API_KEY`; the client converts payloads to the Moonshot JSON schema for you. 6. **Qwen (Qwen3-Next)** - Activate DashScope and retrieve a key with text-generation permissions. - Save the key as `QWEN_API_KEY`; the integration handles the `Authorization: Bearer` header format. After updating `.env`, restart the application so that Gradio reloads the configuration. --- ## Usage Guide 1. **Create or select a project** in the **Projects** tab. Each project stores conversations, specifications, and export history. 2. **Engage with the Requirements Specialist persona** in the **Requirements Chat** tab. Provide business objectives, user roles, and product scenarios. The assistant will log messages and surface candidate user stories. 3. **Switch to the Technical Architect persona** in the **Technical Chat** tab to capture APIs, data models, and system components with full technical depth. 4. **Review generated specifications** in the **Validation** tab. Approve high-quality outputs, request revisions, or reject items that need more context. 5. **Browse approved artefacts** in the **Specifications** tab. Filter by User Stories, Features, API Endpoints, Database Design, or System Architecture. 6. **Export documentation** from the **Export** tab. Download branded HTML or AI-friendly Markdown reports that include metadata, statistics, and links back to conversations. 7. **Manage provider settings** and rotate keys within the **Settings** tab. All changes are persisted locally so you can tailor the stack to your environment. Throughout the workflow, the application captures timestamps and associations between conversations, personas, and specifications for full traceability. --- ## Deployment ### Local (Recommended for Development) - Follow the Quick Start steps above. - To run the app on a custom port, export `GRADIO_SERVER_PORT=XXXX` before launching `python app.py`. - Use tools like `tmux` or `systemd` if you want to keep the application running in the background. ### Hugging Face Spaces Hugging Face Spaces reads the [`config.yaml`](config.yaml) manifest and pinned [`requirements.txt`](requirements.txt) to build and launch the application. 1. Create a new **Gradio** Space and connect it to your fork of the repository. 2. Review the metadata in `config.yaml`; update the title or colour palette if you fork the project. 3. Set the **Space hardware** to at least the default CPU (no GPU required). 4. In the Space **Variables** section, add any provider keys you plan to use (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GOOGLE_API_KEY`, `XAI_API_KEY`, `MOONSHOT_API_KEY`, `QWEN_API_KEY`). Spaces automatically exposes these as environment variables. 5. Optional: provide `NAEXYA_DEFAULT_PROVIDER` to specify which vendor should be called first when multiple keys are present. 6. Save the settings and rebuild the Space. Dependencies are installed from the pinned versions in `requirements.txt`, and `app.py` is used as the entry point. 7. Persistent storage is available under `/data`. The application automatically stores the SQLite database there when running inside a Space. > 💡 No API keys yet? Launch the Space anyway. The interface automatically > enters **demo mode** so you can explore the workflow using the built-in mock > responses, validation queue, and exports without leaving the browser. > 📘 For other hosting targets (e.g., Docker, Railway), reuse the same > environment variables and ensure port `7860` is exposed. --- ## Contributing We welcome pull requests and ideas from the community. To contribute: 1. Fork the repository and create a feature branch (`git checkout -b feature/amazing-idea`). 2. Install dependencies and run the application locally to validate your changes. 3. Add or update documentation, including screenshots if you modify the UI. 4. Run `python -m compileall .` (or the relevant test suite once added) to ensure there are no syntax errors. 5. Submit a pull request describing the motivation, approach, and testing performed. Please follow the existing coding style, docstring conventions, and commit message clarity when contributing. --- ## License Naexya Docs AI is released under the terms of the [MIT License](LICENSE). You are free to self-host, extend, and integrate the project in accordance with the license.