olek/AI_template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add foundational documentation templates to support product design and architecture planning, including ADR, archetypes, LLM systems, dev setup, and shared modules.

Browse Source
This commit is contained in:
olekhondera
2025-12-12 02:31:03 +02:00
parent 5053235e95
commit c905cbb725
26 changed files with 759 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
docs/project-overview.md
View File

@@ -12,10 +12,13 @@
## 1. Project Goal
Provide a universal starting point for new products that leverage AI assistance. The template outlines how to structure documentation and technical decisions for projects that may include data ingestion, processing/classification (rules + embeddings + LLM), human approvals, reporting, and optional billing.
Provide a universal starting point for new products that leverage AI assistance. The template outlines how to structure documentation and technical decisions for **different AI product archetypes** (chat assistants, generation tools, pipelines, agentic automation, internal tools).
Capabilities such as integrations/ingestion, staged processing (rules/embeddings/LLM), human review, reporting, multi‑tenancy, and billing are **optional modules** you can mix & match.
Emphasis areas: trust (auditability, optional reasoning traces), speed (near‑real‑time processing), and clarity (human approvals and transparent reporting), adaptable to your domain.
> **First step:** choose an archetype and modules in `/docs/archetypes.md`, then tailor the rest of this document.
## 2. Target Audience
- Define your primary users and stakeholders for the target domain.
@@ -26,35 +29,36 @@ Emphasis areas: trust (auditability, optional reasoning traces), speed (near‑r
## 3. Unique Value Proposition
1. **Automated processing with explainability**
Rules + embeddings (`pgvector`) first, LLM fallback via a single helper, with optional `reasoning_trace` per record.
2. **Human‑in‑the‑loop approvals**
Review/override UI with optional rule creation; every action is logged (e.g., `source_agent`).
3. **Reliable ingestion**
OAuth2/webhooks for external providers; idempotent event handling; queue workers for retries.
4. **Reporting & optional billing**
Dashboards/exports per tenant; subscription management with tenant‑scoped access control.
5. **Multi‑tenant and secure by design**
Tenant isolation, RBAC, webhook verification, audit log (`EventLog`).
1. **Clear AI interaction surface**
Chat, workflow UI, batch pipeline, or API — with optional explainability (`reasoning_trace`) and trace IDs.
2. **Optional human feedback loop**
Approvals/overrides, edits, ratings, or escalation — all actions audited (`EventLog`, `source_agent`).
3. **Optional integrations & ingestion**
OAuth2/webhooks/files/SDKs; idempotent handling and safe retries.
4. **Optional reporting & billing**
Dashboards/exports and provider‑hosted subscriptions/usage if your product needs them.
5. **Security by design (single‑ or multi‑tenant)**
Tenant isolation and RBAC when applicable; webhook verification and audit logging for all products.
## 4. Key Features (example template)
### 4.1. Onboarding & Integrations
- Tenant signup/login (Clerk/Auth.js or equivalent).
- Connect external data sources (OAuth2, webhooks, file uploads, etc.).
### 4.1. Onboarding & Integrations (optional)
- User/tenant signup/login if your product needs accounts.
- Connect external data sources (OAuth2, webhooks, file uploads, etc.) if you ingest data.
- Configure subscription/billing if applicable.
- Example domain model (multi‑tenant): `Tenant`, `User`, `Record`, `Rule`, `Attachment`, `Report`, `EventLog`, `Embedding`; `EventLog.source_agent` (e.g., default value), `Record.reasoning_trace` JSONB.
- **Example domain model for pipeline products:** `Tenant`, `User`, `Record`, `Rule`, `Attachment`, `Report`, `EventLog`, `Embedding`; `EventLog.source_agent`, `Record.reasoning_trace` JSONB.
Rename or replace with your domain entities for other archetypes (messages, drafts, tasks, etc.).
### 4.2. Ingestion
- Webhooks/workers normalize provider payloads into a unified schema.
- Webhooks/workers normalize provider payloads into a unified schema (if you have ingestion).
- Idempotent writes; deduplication; `INGESTED` events with `source_agent`.
### 4.3. Classification/Processing
- Rule engine first; embeddings similarity next; LLM fallback via `callLLM()`.
- Optionally persist `reasoning_trace` JSONB on records; log `PROCESSED` (or similar).
- If you use staged processing: rules/heuristics → embeddings/RAG → LLM fallback via `callLLM()`.
- Optionally persist `reasoning_trace` JSONB on items; log `PROCESSED` (or similar).
### 4.4. Approval & Rules
- UI for reviewing/overriding outcomes; optional rule creation from overrides.
- UI for reviewing/overriding outcomes; edits/ratings; optional rule creation from overrides (if relevant).
- Log `APPROVED`, `RULE_CREATED`; track who/when/why.
### 4.5. Reporting & Events