adelorenzo/konstruct

Fork 0

Files

Adolfo Delorenzo f1b79dffe0

CI / Backend Tests (push) Has been cancelled

Details

CI / Portal E2E (push) Has been cancelled

Details

docs: update PROJECT.md, add README.md and CHANGELOG.md

- PROJECT.md updated to reflect v1.0 completion (10 phases, 39 plans,
  67 requirements). All key decisions marked as shipped.
- README.md: comprehensive project documentation with quick start,
  architecture, tech stack, configuration, and project structure.
- CHANGELOG.md: detailed changelog covering all 10 phases with
  feature descriptions organized by phase.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-03-26 09:37:55 -06:00

5.4 KiB

Raw Permalink Blame History

Changelog

All notable changes to Konstruct are documented in this file.

[1.0.0] - 2026-03-26

Phase 10: Agent Capabilities

Knowledge base ingestion pipeline — upload PDF, DOCX, PPTX, XLSX, CSV, TXT, Markdown; add URLs (Firecrawl scraping); add YouTube videos (transcript extraction)
Async document processing via Celery — chunk, embed (all-MiniLM-L6-v2), store in pgvector
KB management portal page with drag-and-drop upload, live status polling, delete, reindex
Google Calendar OAuth per tenant — list events, check availability, create events
Token auto-refresh with encrypted DB write-back
Web search connected to Brave Search API (platform-wide key)
Tool executor injects tenant_id/agent_id into all tool handlers
System prompt includes tool result formatting instruction (no raw JSON)

Phase 9: Testing & QA

Playwright E2E test suite — 29 tests across 7 critical flows (login, tenants, agent deploy, chat, RBAC, i18n, mobile)
Cross-browser testing — Chromium, Firefox, WebKit
Visual regression snapshots at 3 viewports (desktop, tablet, mobile)
axe-core accessibility scans on all pages
Lighthouse CI score gating (>= 80 hard floor)
Gitea Actions CI pipeline — backend lint + pytest → portal build + E2E + Lighthouse

Phase 8: Mobile + PWA

Responsive mobile layout with bottom tab bar (Dashboard, Employees, Chat, Usage, More)
Full-screen WhatsApp-style mobile chat with back arrow + agent name header
Visual Viewport API keyboard handling for iOS
PWA manifest with K monogram icons
Service worker (Serwist) with app shell + runtime caching
Web Push notifications (VAPID) with push subscription management
IndexedDB offline message queue with drain-on-reconnect
Smart install prompt on second visit
iOS safe-area support

Phase 7: Multilanguage

Full portal UI localization — English, Spanish, Portuguese
next-intl v4 (cookie-based locale, no URL routing)
Language switcher in sidebar (post-auth) and login page (pre-auth)
Browser locale auto-detection on first visit
Language preference saved to DB, synced to JWT
Agent templates translated in all 3 languages (JSONB translations column)
System prompt language instruction — agents auto-detect and respond in user's language
Localized invitation emails

Phase 6: Web Chat

Real-time WebSocket chat in the portal
Direct LLM streaming from WebSocket handler (bypasses Celery for speed)
Token-by-token streaming via NDJSON → Redis pub-sub → WebSocket
Conversation persistence (web_conversations + web_conversation_messages tables)
Agent picker dialog for new conversations
Markdown rendering (react-markdown + remark-gfm)
Typing indicator during LLM generation
All roles can chat (operators included)

Phase 5: Employee Design

Three-path AI employee creation: Templates / Guided Setup / Advanced
6 pre-built agent templates (Customer Support Rep, Sales Assistant, Marketing Manager, Office Manager, Project Coordinator, Finance & Accounting Manager)
5-step wizard (Role → Persona → Tools → Channels → Escalation)
System prompt auto-generation from wizard inputs
Templates stored as DB seed data with one-click deploy
Agent Designer as "Advanced" mode

Phase 4: RBAC

Three-tier roles: platform_admin, customer_admin, customer_operator
FastAPI RBAC guard dependencies (require_platform_admin, require_tenant_admin, require_tenant_member)
Email invitation flow with HMAC tokens (48-hour expiry, resend capability)
SMTP email sending via Python stdlib
Portal navigation and API endpoints enforce role-based access
Impersonation for platform admins with audit trail
Global user management page

Phase 3: Operator Experience

Slack OAuth "Add to Slack" flow with HMAC state protection
WhatsApp guided manual setup
3-step onboarding wizard (Connect → Configure → Test)
Stripe subscription management (per-agent $49/month, 14-day trial)
BYO API key management with Fernet encryption + MultiFernet key rotation
Cost dashboard with Recharts (token usage, provider costs, message volume, budget alerts)
Agent-level cost tracking and budget limits

Phase 2: Agent Features

Two-layer conversational memory (Redis sliding window + pgvector HNSW)
Cross-conversation memory keyed per-user per-agent
Tool framework with 4 built-in tools (web search, KB search, HTTP request, calendar)
Schema-validated tool execution with confirmation flow for side-effecting actions
Immutable audit logging (REVOKE UPDATE/DELETE at DB level)
WhatsApp Business Cloud API adapter with Meta 2026 policy compliance
Two-tier business-function scoping (keyword allowlist + role-based LLM)
Human escalation with DM delivery, full transcript, and assistant mode
Cross-channel bidirectional media support with multimodal LLM interpretation

Phase 1: Foundation

Monorepo with uv workspaces
Docker Compose dev environment (PostgreSQL 16 + pgvector, Redis, Ollama)
PostgreSQL Row Level Security with FORCE ROW LEVEL SECURITY
Shared Pydantic models (KonstructMessage) and SQLAlchemy 2.0 async ORM
LiteLLM Router with Ollama + Anthropic/OpenAI and fallback routing
Celery orchestrator with sync-def pattern (asyncio.run)
Slack adapter (Events API) with typing indicator
Message Router with tenant resolution, rate limiting, idempotency
Next.js 16 admin portal with Auth.js v5, tenant CRUD, Agent Designer
Premium UI design system (indigo brand, dark sidebar, glass-morphism, DM Sans)

5.4 KiB Raw Permalink Blame History