@nextsparkjs/plugin-ai 0.1.0-beta.44 → 0.1.0-beta.45

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/api/ai-history/docs.md +135 -0
  2. package/api/ai-history/presets.ts +56 -0
  3. package/api/embeddings/docs.md +137 -0
  4. package/api/embeddings/presets.ts +41 -0
  5. package/api/generate/docs.md +157 -0
  6. package/api/generate/presets.ts +88 -0
  7. package/package.json +2 -2
package/api/ai-history/docs.md ADDED
@@ -0,0 +1,135 @@
1
+ # AI History API
2
+
3
+ Manage AI operation history and link AI interactions to entities.
4
+
5
+ ## Endpoint
6
+
7
+ ```
8
+ PATCH /api/v1/plugin/ai/ai-history/:id
9
+ ```
10
+
11
+ ## Authentication
12
+
13
+ Requires session authentication.
14
+
15
+ **Headers:**
16
+ ```
17
+ Authorization: Bearer <session-token>
18
+ ```
19
+
20
+ ## PATCH - Link AI History to Entity
21
+
22
+ Update the related entity information for an AI history record. Used to link AI operations (e.g., analysis results) to entities created afterward.
23
+
24
+ ### Path Parameters
25
+
26
+ | Parameter | Type | Description |
27
+ |-----------|------|-------------|
28
+ | `id` | string | AI history record ID |
29
+
30
+ ### Request Body
31
+
32
+ | Field | Type | Required | Description |
33
+ |-------|------|----------|-------------|
34
+ | `relatedEntityType` | string | Yes | Entity type (e.g., "clients", "projects") |
35
+ | `relatedEntityId` | string | Yes | Entity ID to link |
36
+
37
+ ### Example Request
38
+
39
+ ```
40
+ PATCH /api/v1/plugin/ai/ai-history/hist_abc123
41
+ ```
42
+
43
+ ```json
44
+ {
45
+ "relatedEntityType": "clients",
46
+ "relatedEntityId": "client_xyz789"
47
+ }
48
+ ```
49
+
50
+ ### Success Response (200)
51
+
52
+ ```json
53
+ {
54
+ "success": true,
55
+ "message": "AI history record linked to entity successfully",
56
+ "data": {
57
+ "historyId": "hist_abc123",
58
+ "relatedEntityType": "clients",
59
+ "relatedEntityId": "client_xyz789"
60
+ }
61
+ }
62
+ ```
63
+
64
+ ## Error Responses
65
+
66
+ | Status | Error | Description |
67
+ |--------|-------|-------------|
68
+ | 400 | Missing history ID | No ID provided in URL |
69
+ | 400 | Missing required fields | relatedEntityType or relatedEntityId missing |
70
+ | 401 | Unauthorized | Not authenticated |
71
+ | 403 | Forbidden | Record belongs to another user |
72
+ | 404 | Not found | AI history record doesn't exist |
73
+ | 500 | Internal server error | Database or server error |
74
+
75
+ ### Example Error (403)
76
+
77
+ ```json
78
+ {
79
+ "error": "Forbidden - this record belongs to another user"
80
+ }
81
+ ```
82
+
83
+ ### Example Error (400)
84
+
85
+ ```json
86
+ {
87
+ "error": "Missing required fields",
88
+ "details": "Both relatedEntityType and relatedEntityId are required"
89
+ }
90
+ ```
91
+
92
+ ## Use Cases
93
+
94
+ 1. **Brief Analysis Linking**: After analyzing a client brief with AI, link the analysis to the client record created from it
95
+ 2. **Content Generation Tracking**: Link generated content to the project or campaign it was created for
96
+ 3. **Audit Trail**: Maintain a complete audit trail of AI operations and their resulting entities
97
+
98
+ ## Workflow Example
99
+
100
+ ```typescript
101
+ // 1. Generate AI analysis
102
+ const analysis = await fetch('/api/v1/plugin/ai/generate', {
103
+ method: 'POST',
104
+ body: JSON.stringify({
105
+ prompt: 'Analyze this client brief...',
106
+ saveExample: true
107
+ })
108
+ })
109
+
110
+ // 2. Create entity from analysis
111
+ const client = await fetch('/api/v1/clients', {
112
+ method: 'POST',
113
+ body: JSON.stringify({ name: 'New Client', ... })
114
+ })
115
+
116
+ // 3. Link AI history to created entity
117
+ await fetch(`/api/v1/plugin/ai/ai-history/${analysis.historyId}`, {
118
+ method: 'PATCH',
119
+ body: JSON.stringify({
120
+ relatedEntityType: 'clients',
121
+ relatedEntityId: client.id
122
+ })
123
+ })
124
+ ```
125
+
126
+ ## Security
127
+
128
+ - Users can only update their own AI history records
129
+ - Record ownership is verified before any modification
130
+ - All operations are logged for audit purposes
131
+
132
+ ## Related APIs
133
+
134
+ - [AI Generate](/api/v1/plugin/ai/generate) - Generate AI responses
135
+ - [AI Embeddings](/api/v1/plugin/ai/embeddings) - Generate text embeddings
package/api/ai-history/presets.ts ADDED
@@ -0,0 +1,56 @@
1
+ /**
2
+ * API Presets for AI History
3
+ *
4
+ * Manage AI operation history and entity linking
5
+ */
6
+
7
+ import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
8
+
9
+ export default defineApiEndpoint({
10
+ endpoint: '/api/v1/plugin/ai/ai-history/:id',
11
+ summary: 'Link AI history records to related entities',
12
+ presets: [
13
+ {
14
+ id: 'link-to-client',
15
+ title: 'Link to Client',
16
+ description: 'Link AI history to a client entity',
17
+ method: 'PATCH',
18
+ pathParams: {
19
+ id: '{{historyId}}'
20
+ },
21
+ payload: {
22
+ relatedEntityType: 'clients',
23
+ relatedEntityId: '{{clientId}}'
24
+ },
25
+ tags: ['write', 'update']
26
+ },
27
+ {
28
+ id: 'link-to-project',
29
+ title: 'Link to Project',
30
+ description: 'Link AI history to a project entity',
31
+ method: 'PATCH',
32
+ pathParams: {
33
+ id: '{{historyId}}'
34
+ },
35
+ payload: {
36
+ relatedEntityType: 'projects',
37
+ relatedEntityId: '{{projectId}}'
38
+ },
39
+ tags: ['write', 'update']
40
+ },
41
+ {
42
+ id: 'link-to-entity',
43
+ title: 'Link to Entity',
44
+ description: 'Link AI history to any entity type',
45
+ method: 'PATCH',
46
+ pathParams: {
47
+ id: '{{historyId}}'
48
+ },
49
+ payload: {
50
+ relatedEntityType: '{{entityType}}',
51
+ relatedEntityId: '{{entityId}}'
52
+ },
53
+ tags: ['write', 'update']
54
+ }
55
+ ]
56
+ })
package/api/embeddings/docs.md ADDED
@@ -0,0 +1,137 @@
1
+ # AI Embeddings API
2
+
3
+ Generate text embeddings using OpenAI's text-embedding-3-small model.
4
+
5
+ ## Endpoint
6
+
7
+ ```
8
+ POST /api/v1/plugin/ai/embeddings
9
+ GET /api/v1/plugin/ai/embeddings
10
+ ```
11
+
12
+ ## Authentication
13
+
14
+ Requires dual authentication (session or API key).
15
+
16
+ **Headers:**
17
+ ```
18
+ Authorization: Bearer <session-token>
19
+ # OR
20
+ x-api-key: <api-key>
21
+ x-team-id: <team-id>
22
+ ```
23
+
24
+ ## POST - Generate Embedding
25
+
26
+ Convert text into a vector representation for semantic search, similarity comparison, or machine learning applications.
27
+
28
+ ### Request Body
29
+
30
+ | Field | Type | Required | Description |
31
+ |-------|------|----------|-------------|
32
+ | `text` | string | Yes | Text to convert to embedding (1-50,000 chars) |
33
+
34
+ ### Example Request
35
+
36
+ ```json
37
+ {
38
+ "text": "Premium wireless headphones with noise cancellation"
39
+ }
40
+ ```
41
+
42
+ ### Success Response (200)
43
+
44
+ ```json
45
+ {
46
+ "success": true,
47
+ "embedding": [0.123, -0.456, 0.789, ...],
48
+ "model": "text-embedding-3-small",
49
+ "dimensions": 1536,
50
+ "tokens": 8,
51
+ "userId": "user_xxx"
52
+ }
53
+ ```
54
+
55
+ ### Response Fields
56
+
57
+ | Field | Type | Description |
58
+ |-------|------|-------------|
59
+ | `embedding` | number[] | Vector representation (1536 dimensions) |
60
+ | `model` | string | Model used (text-embedding-3-small) |
61
+ | `dimensions` | number | Embedding dimensions (always 1536) |
62
+ | `tokens` | number | Tokens consumed |
63
+ | `userId` | string | Authenticated user ID |
64
+
65
+ ## GET - Endpoint Info
66
+
67
+ Returns endpoint documentation and usage information.
68
+
69
+ ### Success Response (200)
70
+
71
+ ```json
72
+ {
73
+ "endpoint": "/api/v1/plugin/ai/embeddings",
74
+ "description": "Generate text embeddings using OpenAI",
75
+ "usage": { ... },
76
+ "response": { ... },
77
+ "example": { ... },
78
+ "model": {
79
+ "name": "text-embedding-3-small",
80
+ "dimensions": 1536,
81
+ "maxTokens": 8191,
82
+ "cost": "$0.00002 per 1K tokens"
83
+ }
84
+ }
85
+ ```
86
+
87
+ ## Error Responses
88
+
89
+ | Status | Error | Description |
90
+ |--------|-------|-------------|
91
+ | 400 | Validation failed | Invalid or missing text field |
92
+ | 401 | Authentication required | Missing or invalid credentials |
93
+ | 503 | Plugin not configured | OpenAI API key not set |
94
+
95
+ ### Example Error
96
+
97
+ ```json
98
+ {
99
+ "error": "Validation failed",
100
+ "details": [
101
+ {
102
+ "code": "too_small",
103
+ "minimum": 1,
104
+ "path": ["text"],
105
+ "message": "Text cannot be empty"
106
+ }
107
+ ]
108
+ }
109
+ ```
110
+
111
+ ## Setup
112
+
113
+ Add your OpenAI API key to the plugin's environment file:
114
+
115
+ ```bash
116
+ # plugins/ai/.env
117
+ OPENAI_API_KEY=sk-...
118
+ ```
119
+
120
+ ## Use Cases
121
+
122
+ 1. **Semantic Search**: Convert documents and queries to vectors for similarity search
123
+ 2. **Content Recommendation**: Find similar content based on vector similarity
124
+ 3. **Clustering**: Group similar texts together
125
+ 4. **Classification**: Use embeddings as features for ML models
126
+
127
+ ## Model Information
128
+
129
+ - **Model**: text-embedding-3-small
130
+ - **Dimensions**: 1536
131
+ - **Max Tokens**: 8,191
132
+ - **Cost**: $0.00002 per 1K tokens (5x cheaper than ada-002)
133
+
134
+ ## Related APIs
135
+
136
+ - [AI Generate](/api/v1/plugin/ai/generate) - Generate AI text responses
137
+ - [AI History](/api/v1/plugin/ai/ai-history) - Track AI operations
package/api/embeddings/presets.ts ADDED
@@ -0,0 +1,41 @@
1
+ /**
2
+ * API Presets for AI Embeddings
3
+ *
4
+ * Generate text embeddings using OpenAI
5
+ */
6
+
7
+ import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
8
+
9
+ export default defineApiEndpoint({
10
+ endpoint: '/api/v1/plugin/ai/embeddings',
11
+ summary: 'Generate text embeddings using OpenAI text-embedding-3-small model',
12
+ presets: [
13
+ {
14
+ id: 'generate-embedding',
15
+ title: 'Generate Embedding',
16
+ description: 'Convert text to vector representation',
17
+ method: 'POST',
18
+ payload: {
19
+ text: 'Premium wireless headphones with noise cancellation'
20
+ },
21
+ tags: ['write', 'ai']
22
+ },
23
+ {
24
+ id: 'generate-long-text',
25
+ title: 'Embed Long Text',
26
+ description: 'Generate embedding for longer content',
27
+ method: 'POST',
28
+ payload: {
29
+ text: '{{longText}}'
30
+ },
31
+ tags: ['write', 'ai']
32
+ },
33
+ {
34
+ id: 'get-endpoint-info',
35
+ title: 'Get Endpoint Info',
36
+ description: 'Get embedding endpoint documentation',
37
+ method: 'GET',
38
+ tags: ['read', 'info']
39
+ }
40
+ ]
41
+ })
package/api/generate/docs.md ADDED
@@ -0,0 +1,157 @@
1
+ # AI Generate API
2
+
3
+ Simple AI assistant endpoint for generating text responses using multiple providers (OpenAI, Anthropic, Ollama).
4
+
5
+ ## Endpoint
6
+
7
+ ```
8
+ POST /api/v1/plugin/ai/generate
9
+ GET /api/v1/plugin/ai/generate
10
+ ```
11
+
12
+ ## Authentication
13
+
14
+ Requires dual authentication (session or API key).
15
+
16
+ **Headers:**
17
+ ```
18
+ Authorization: Bearer <session-token>
19
+ # OR
20
+ x-api-key: <api-key>
21
+ x-team-id: <team-id>
22
+ ```
23
+
24
+ ## POST - Generate AI Response
25
+
26
+ Generate an AI response to a prompt using the configured model.
27
+
28
+ ### Request Body
29
+
30
+ | Field | Type | Required | Default | Description |
31
+ |-------|------|----------|---------|-------------|
32
+ | `prompt` | string | Yes | - | Your question or request (1-10,000 chars) |
33
+ | `model` | string | No | Config default | AI model to use |
34
+ | `maxTokens` | number | No | Config default | Max response length (1-10,000) |
35
+ | `temperature` | number | No | Config default | Response creativity (0-1) |
36
+ | `saveExample` | boolean | No | false | Save interaction as example |
37
+
38
+ ### Available Models
39
+
40
+ **Local (Ollama):**
41
+ - `llama3.2:3b`, `llama3.2`, `llama3.1`
42
+ - `qwen2.5`, `mistral`
43
+
44
+ **OpenAI:**
45
+ - `gpt-4o`, `gpt-4o-mini`, `gpt-3.5-turbo`
46
+
47
+ **Anthropic:**
48
+ - `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022`
49
+
50
+ ### Example Request
51
+
52
+ ```json
53
+ {
54
+ "prompt": "Explain quantum computing in simple terms",
55
+ "model": "gpt-4o-mini",
56
+ "maxTokens": 500,
57
+ "temperature": 0.7
58
+ }
59
+ ```
60
+
61
+ ### Success Response (200)
62
+
63
+ ```json
64
+ {
65
+ "success": true,
66
+ "response": "Quantum computing is...",
67
+ "model": "gpt-4o-mini",
68
+ "provider": "openai",
69
+ "isLocal": false,
70
+ "cost": 0.00015,
71
+ "tokens": {
72
+ "prompt": 12,
73
+ "completion": 150,
74
+ "total": 162
75
+ },
76
+ "userId": "user_xxx",
77
+ "exampleSaved": false
78
+ }
79
+ ```
80
+
81
+ ### Response Fields
82
+
83
+ | Field | Type | Description |
84
+ |-------|------|-------------|
85
+ | `response` | string | AI-generated text response |
86
+ | `model` | string | Model used for generation |
87
+ | `provider` | string | Provider (openai, anthropic, ollama) |
88
+ | `isLocal` | boolean | Whether using local model |
89
+ | `cost` | number | Estimated cost in USD |
90
+ | `tokens` | object | Token usage breakdown |
91
+ | `exampleSaved` | boolean | Whether interaction was saved |
92
+
93
+ ## GET - Endpoint Info
94
+
95
+ Returns endpoint documentation with available models and setup instructions.
96
+
97
+ ### Success Response (200)
98
+
99
+ ```json
100
+ {
101
+ "endpoint": "/api/plugin/ai/generate",
102
+ "description": "Simple AI assistant endpoint",
103
+ "usage": { ... },
104
+ "example": { ... },
105
+ "models": {
106
+ "local": ["llama3.2:3b", "llama3.2", ...],
107
+ "openai": ["gpt-4o", "gpt-4o-mini", ...],
108
+ "anthropic": ["claude-3-5-sonnet-20241022", ...]
109
+ },
110
+ "setup": { ... }
111
+ }
112
+ ```
113
+
114
+ ## Error Responses
115
+
116
+ | Status | Error | Description |
117
+ |--------|-------|-------------|
118
+ | 400 | Validation failed | Invalid request parameters |
119
+ | 401 | Authentication required | Missing or invalid credentials |
120
+ | 503 | Plugin not configured | API keys not set |
121
+
122
+ ## Setup
123
+
124
+ Configure API keys in the plugin's environment file:
125
+
126
+ ```bash
127
+ # plugins/ai/.env
128
+
129
+ # For OpenAI models
130
+ OPENAI_API_KEY=sk-...
131
+
132
+ # For Anthropic models
133
+ ANTHROPIC_API_KEY=sk-ant-...
134
+
135
+ # For local models (Ollama)
136
+ # Run: ollama serve && ollama pull llama3.2
137
+ ```
138
+
139
+ ## Use Cases
140
+
141
+ 1. **Content Generation**: Generate blog posts, descriptions, summaries
142
+ 2. **Code Assistance**: Generate code snippets, explain code
143
+ 3. **Customer Support**: Automated responses, FAQ handling
144
+ 4. **Analysis**: Analyze text, extract insights
145
+
146
+ ## Cost Configuration
147
+
148
+ The plugin tracks costs based on model pricing:
149
+ - OpenAI GPT-4o: ~$0.01/1K tokens
150
+ - OpenAI GPT-4o-mini: ~$0.00015/1K tokens
151
+ - Anthropic Claude: ~$0.003/1K tokens
152
+ - Local Ollama: Free
153
+
154
+ ## Related APIs
155
+
156
+ - [AI Embeddings](/api/v1/plugin/ai/embeddings) - Generate text embeddings
157
+ - [AI History](/api/v1/plugin/ai/ai-history) - Track AI operations
package/api/generate/presets.ts ADDED
@@ -0,0 +1,88 @@
1
+ /**
2
+ * API Presets for AI Generate
3
+ *
4
+ * Generate AI text responses using multiple providers
5
+ */
6
+
7
+ import { defineApiEndpoint } from '@nextsparkjs/core/types/api-presets'
8
+
9
+ export default defineApiEndpoint({
10
+ endpoint: '/api/v1/plugin/ai/generate',
11
+ summary: 'Generate AI text responses using OpenAI, Anthropic, or Ollama',
12
+ presets: [
13
+ {
14
+ id: 'simple-prompt',
15
+ title: 'Simple Prompt',
16
+ description: 'Generate response with default settings',
17
+ method: 'POST',
18
+ payload: {
19
+ prompt: 'Explain quantum computing in simple terms'
20
+ },
21
+ tags: ['write', 'ai']
22
+ },
23
+ {
24
+ id: 'with-model',
25
+ title: 'With Specific Model',
26
+ description: 'Generate using a specific AI model',
27
+ method: 'POST',
28
+ payload: {
29
+ prompt: '{{prompt}}',
30
+ model: 'gpt-4o-mini'
31
+ },
32
+ tags: ['write', 'ai']
33
+ },
34
+ {
35
+ id: 'creative-response',
36
+ title: 'Creative Response',
37
+ description: 'Generate with high temperature for creativity',
38
+ method: 'POST',
39
+ payload: {
40
+ prompt: '{{prompt}}',
41
+ temperature: 0.9,
42
+ maxTokens: 1000
43
+ },
44
+ tags: ['write', 'ai']
45
+ },
46
+ {
47
+ id: 'precise-response',
48
+ title: 'Precise Response',
49
+ description: 'Generate with low temperature for accuracy',
50
+ method: 'POST',
51
+ payload: {
52
+ prompt: '{{prompt}}',
53
+ temperature: 0.1,
54
+ maxTokens: 500
55
+ },
56
+ tags: ['write', 'ai']
57
+ },
58
+ {
59
+ id: 'save-example',
60
+ title: 'Save as Example',
61
+ description: 'Generate and save interaction for training',
62
+ method: 'POST',
63
+ payload: {
64
+ prompt: '{{prompt}}',
65
+ saveExample: true
66
+ },
67
+ tags: ['write', 'ai']
68
+ },
69
+ {
70
+ id: 'local-model',
71
+ title: 'Use Local Model',
72
+ description: 'Generate using Ollama local model',
73
+ method: 'POST',
74
+ payload: {
75
+ prompt: '{{prompt}}',
76
+ model: 'llama3.2:3b'
77
+ },
78
+ tags: ['write', 'ai', 'local']
79
+ },
80
+ {
81
+ id: 'get-endpoint-info',
82
+ title: 'Get Endpoint Info',
83
+ description: 'Get available models and configuration',
84
+ method: 'GET',
85
+ tags: ['read', 'info']
86
+ }
87
+ ]
88
+ })
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nextsparkjs/plugin-ai",
3
- "version": "0.1.0-beta.44",
3
+ "version": "0.1.0-beta.45",
4
4
  "private": false,
5
5
  "main": "./plugin.config.ts",
6
6
  "requiredPlugins": [],
@@ -18,7 +18,7 @@
18
18
  "react": "^19.0.0",
19
19
  "react-dom": "^19.0.0",
20
20
  "zod": "^4.0.0",
21
- "@nextsparkjs/core": "0.1.0-beta.44"
21
+ "@nextsparkjs/core": "0.1.0-beta.45"
22
22
  },
23
23
  "nextspark": {
24
24
  "type": "plugin",