KnoksPix – AI-Powered Image & Code Companion

KnoksPix is an AI-first creative workspace combining:

• Intelligent image editing & adjustment workflow
• Generative augmentation via Gemini / (optional) local Starcoder2 backend
• Cross‑platform delivery (Web + Desktop [Electron] + Mobile [Capacitor/Android])
• Extensible architecture (pluggable model backends & tools)

Demo: View the app in AI Studio

Table of Contents

1. Core Features
2. Screenshots
3. Quick Start
4. Frontend
5. Backend API (Starcoder2)
6. Deployment Options
7. Preview Deployments
8. Environment Variables
9. Testing
10. Architecture
11. Security
12. Release Checklist
13. Contributing
14. License

Features

Screenshots

Quick Start

Frontend Only (using hosted Gemini)

git clone https://github.com/knoksen/knoksPix.git
cd knoksPix
npm ci
echo "GEMINI_API_KEY=your_key" > .env.local
npm run dev

Open http://localhost:5173

Full Stack (with local Starcoder2 backend)

cp backend/.env.sample backend/.env
# Edit backend/.env as needed (MODEL_ID, tokens, mock mode etc.)
docker compose up --build
# Frontend (separate terminal)
npm run dev

Backend API docs: http://localhost:8000/docs

Frontend

React + TypeScript + Vite. Core UI elements in components/. State is localized per panel keeping bundle size lean. Tests under tests/ use Jest + React Testing Library.

Build production bundle:

npm run build

Serve locally:

npm run preview

Backend API Service (Starcoder2)

Located in backend/. Provides:

• POST /v1/chat/completions – OpenAI-style (stream or non-stream)
• POST /v1/generate – Simple prompt generation (stream or non-stream)
• GET /metrics – Prometheus metrics
• GET /healthz – Liveness check

Streaming uses Server-Sent Events (SSE). Chat endpoint emits OpenAI-compatible chat.completion.chunk objects. Generation endpoint emits { "text": "..." } chunks then [DONE] sentinel.

Mock Mode (no model download): set USE_MOCK_GENERATION=1.

Backend Setup

cd backend
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\\Scripts\\activate
pip install -r requirements.txt -r requirements-dev.txt
cp .env.sample .env  # edit values
uvicorn main:app --reload --port 8000

Configuration Reference

Streaming Protocol Details

Chat endpoint (/v1/chat/completions, stream=true):

data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":"def"}}]}
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{"content":" add"}}]}
data: {"id":"...","object":"chat.completion.chunk","choices":[{"delta":{}}],"finish_reason":"stop"}
data: [DONE]

Generate endpoint (/v1/generate, stream=true):

data: {"text":"partial token"}
data: {"text":" more"}
data: [DONE]

Both endpoints send text/event-stream; charset=utf-8 and can be consumed with any SSE client. Non‑stream mode aggregates full text in a single JSON object.

Observability

Metric names (Prometheus):

• http_requests_total / latency histograms (instrumentator defaults)
• Custom counters (planned): token usage per request (placeholder if not yet present)

Dashboards: Point Grafana at the Prometheus service (see docker-compose.yml).

Performance Notes

• Use mock mode in CI to avoid multi‑GB model pulls.
• For GPU: extend Dockerfile build args (CUDA / ROCm) and launch with --gpus=all (already hinted in compose).
• Adjust MAX_NEW_TOKENS_LIMIT to guard latency & memory.
• Consider swapping to a TextIteratorStreamer for finer token pacing (roadmap).

Example (chat streaming):

curl -N \
   -H "Authorization: Bearer $STARCODER2_API_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
      "model": "bigcode/starcoder2-3b",
      "messages": [{"role":"user","content":"Write a Python hello world"}],
      "stream": true
   }' \
   http://localhost:8000/v1/chat/completions

Example (generate streaming):

curl -N \
   -H "Authorization: Bearer $STARCODER2_API_TOKEN" \
   -H "Content-Type: application/json" \
   -d '{
      "prompt": "def add(a,b):\n    return a+b",
      "max_new_tokens": 64,
      "stream": true
   }' \
   http://localhost:8000/v1/generate

Python Helper Client

from starcoder2_client import ChatClient
client = ChatClient(base_url="http://localhost:8000", token="changeme")
resp = client.chat([{ "role": "user", "content": "Write a Python function add(a,b)." }])
print(resp["choices"][0]["message"]["content"])

Deployment Options

Simplified here. Full extended matrices, one‑click buttons, hosting comparisons, and hardening tips moved to docs/DEPLOYMENT.md.

Common quick paths:

See docs/DEPLOYMENT.md for buttons & providers.

Badges:

Preview Deployments

• Each PR triggers a build + Surge deployment.
• A unique URL is commented automatically on the PR.
• Main branch builds to GitHub Pages (frontend) + can trigger backend container build (optional pipeline extension).

Environment Variables

Frontend (.env.local):

GEMINI_API_KEY=your_key
VITE_API_BASE=http://localhost:8000

Backend (backend/.env): (see backend/.env.sample for full list)

MODEL_ID=bigcode/starcoder2-3b
STARCODER2_API_TOKEN=changeme
USE_MOCK_GENERATION=1
RATE_LIMIT=100/minute
MAX_NEW_TOKENS_LIMIT=512
LOG_LEVEL=INFO

Testing

Run UI tests:

npm test

Backend tests (mock mode):

pytest

Architecture

flowchart LR
   A[React/Vite Frontend] -->|Fetch / Chat| B((FastAPI Backend))
   B -->|Generation| C[Starcoder2 Model]
   B -->|Mock Mode| C2[(In-Memory Mock)]
   B -->|/metrics| D[(Prometheus)]
   D --> G[Grafana]
   B -->|Structured Logs| L[(Log Aggregator)]

• Rate limiting: slowapi sliding window
• Streaming: SSE for both chat + generate
• Metrics: latency, request counts, token counter
• Multi-platform packaging: Electron + Capacitor

Security

• Secrets only via environment variables
• Bearer token auth on backend when token set
• Rate limiting enabled by default
• No secrets shipped in PR preview builds

Release Checklist

Run Locally (Frontend)

Prerequisites: Node.js 20 or higher

1. Clone the repository:

bash git clone https://github.com/knoksen/knoksPix.git cd knoksPix

1. Install dependencies:

bash npm ci

1. Set up environment variables:
2. Create a .env.local file in the root directory

3. Add your Gemini API key: GEMINI_API_KEY=your_api_key_here

4. Start the development server:

bash npm run dev

1. Open http://localhost:5173 in your browser

Local Backend + Frontend Together

1. Start backend (mock for speed):

bash (cd backend && USE_MOCK_GENERATION=1 uvicorn main:app --port 8000)

1. Start frontend:

bash npm run dev

1. Set VITE_API_BASE=http://localhost:8000 in .env.local if calling backend.

Deployment

See Deployment Options for matrix. Production frontend is emitted to dist/.

License

MIT. See LICENSE.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feat/awesome
3. Commit: git commit -m 'feat: add awesome capability'
4. Push: git push origin feat/awesome
5. Open a Pull Request – preview URL will be auto‑attached.

Conventional commit prefixes (feat:, fix:, docs:) encouraged. Small, focused PRs merge faster.