coaiajs 0.3.0 → 0.3.2
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.
- package/KINSHIP.md +1 -1
- package/README.md +191 -75
- package/dist/mcp/config.d.ts.map +1 -0
- package/dist/mcp/config.js +0 -2
- package/dist/mcp/config.js.map +1 -0
- package/dist/mcp/prompts.d.ts.map +1 -0
- package/dist/mcp/prompts.js.map +1 -0
- package/dist/mcp/resources.d.ts.map +1 -0
- package/dist/mcp/resources.js.map +1 -0
- package/dist/mcp/server.d.ts.map +1 -0
- package/dist/mcp/server.js +1 -1
- package/dist/mcp/server.js.map +1 -0
- package/dist/mcp/tools/coaiapy-tools.d.ts.map +1 -0
- package/dist/mcp/tools/coaiapy-tools.js.map +1 -0
- package/dist/mcp/tools/index.d.ts.map +1 -0
- package/dist/mcp/tools/index.js.map +1 -0
- package/dist/src/audio.d.ts.map +1 -0
- package/dist/src/audio.js.map +1 -0
- package/dist/src/cli-helpers.d.ts.map +1 -0
- package/dist/src/cli-helpers.js.map +1 -0
- package/dist/src/cli.d.ts.map +1 -0
- package/dist/src/cli.js +1 -0
- package/dist/src/cli.js.map +1 -0
- package/dist/src/config.d.ts.map +1 -0
- package/dist/src/config.js.map +1 -0
- package/dist/src/environment.d.ts.map +1 -0
- package/dist/src/environment.js.map +1 -0
- package/dist/src/github.d.ts.map +1 -0
- package/dist/src/github.js.map +1 -0
- package/dist/src/index.d.ts +1 -0
- package/dist/src/index.d.ts.map +1 -0
- package/dist/src/index.js +1 -0
- package/dist/src/index.js.map +1 -0
- package/dist/src/langfuse/client.d.ts.map +1 -0
- package/dist/src/langfuse/client.js.map +1 -0
- package/dist/src/langfuse/comments.d.ts.map +1 -0
- package/dist/src/langfuse/comments.js.map +1 -0
- package/dist/src/langfuse/datasets.d.ts.map +1 -0
- package/dist/src/langfuse/datasets.js.map +1 -0
- package/dist/src/langfuse/index.d.ts +1 -0
- package/dist/src/langfuse/index.d.ts.map +1 -0
- package/dist/src/langfuse/index.js.map +1 -0
- package/dist/src/langfuse/media.d.ts.map +1 -0
- package/dist/src/langfuse/media.js.map +1 -0
- package/dist/src/langfuse/observations.d.ts.map +1 -0
- package/dist/src/langfuse/observations.js.map +1 -0
- package/dist/src/langfuse/prompts.d.ts +5 -1
- package/dist/src/langfuse/prompts.d.ts.map +1 -0
- package/dist/src/langfuse/prompts.js +16 -3
- package/dist/src/langfuse/prompts.js.map +1 -0
- package/dist/src/langfuse/scores.d.ts.map +1 -0
- package/dist/src/langfuse/scores.js.map +1 -0
- package/dist/src/langfuse/traces.d.ts.map +1 -0
- package/dist/src/langfuse/traces.js.map +1 -0
- package/dist/src/llm.d.ts.map +1 -0
- package/dist/src/llm.js.map +1 -0
- package/dist/src/narrative/graph-manager.d.ts.map +1 -0
- package/dist/src/narrative/graph-manager.js.map +1 -0
- package/dist/src/narrative/index.d.ts.map +1 -0
- package/dist/src/narrative/index.js.map +1 -0
- package/dist/src/narrative/markdown-export.d.ts.map +1 -0
- package/dist/src/narrative/markdown-export.js.map +1 -0
- package/dist/src/narrative/tool-definitions.d.ts.map +1 -0
- package/dist/src/narrative/tool-definitions.js.map +1 -0
- package/dist/src/narrative/tool-handlers.d.ts.map +1 -0
- package/dist/src/narrative/tool-handlers.js.map +1 -0
- package/dist/src/narrative/types.d.ts.map +1 -0
- package/dist/src/narrative/types.js.map +1 -0
- package/dist/src/narrative/validation.d.ts.map +1 -0
- package/dist/src/narrative/validation.js.map +1 -0
- package/dist/src/pde/index.d.ts.map +1 -0
- package/dist/src/pde/index.js.map +1 -0
- package/dist/src/pde/mcp-handlers.d.ts.map +1 -0
- package/dist/src/pde/mcp-handlers.js.map +1 -0
- package/dist/src/pde/mcp-tools.d.ts.map +1 -0
- package/dist/src/pde/mcp-tools.js.map +1 -0
- package/dist/src/pde/session-manager.d.ts.map +1 -0
- package/dist/src/pde/session-manager.js.map +1 -0
- package/dist/src/pde/stc-mapper.d.ts.map +1 -0
- package/dist/src/pde/stc-mapper.js.map +1 -0
- package/dist/src/pipeline/index.d.ts.map +1 -0
- package/dist/src/pipeline/index.js.map +1 -0
- package/dist/src/pipeline/template-engine.d.ts.map +1 -0
- package/dist/src/pipeline/template-engine.js.map +1 -0
- package/dist/src/planning/index.d.ts.map +1 -0
- package/dist/src/planning/index.js.map +1 -0
- package/dist/src/planning/mcp-handlers.d.ts.map +1 -0
- package/dist/src/planning/mcp-handlers.js.map +1 -0
- package/dist/src/planning/mcp-tools.d.ts.map +1 -0
- package/dist/src/planning/mcp-tools.js.map +1 -0
- package/dist/src/planning/plan-parser.d.ts.map +1 -0
- package/dist/src/planning/plan-parser.js.map +1 -0
- package/dist/src/redis.d.ts.map +1 -0
- package/dist/src/redis.js.map +1 -0
- package/dist/src/types.d.ts.map +1 -0
- package/dist/src/types.js.map +1 -0
- package/dist/src/version.d.ts.map +1 -0
- package/dist/src/version.js.map +1 -0
- package/llms-full.txt +361 -0
- package/llms.txt +43 -0
- package/package.json +79 -12
- package/.claude/settings.local.json +0 -17
- package/.claude-plugin/marketplace.json +0 -26
- package/articles/academic/NOTES.md +0 -1
- package/articles/academic/README.md +0 -1
- package/articles/academic/creative-orientation-vs-problem-solving.md +0 -177
- package/articles/academic/jsonl-knowledge-graphs-agent-memory.md +0 -142
- package/articles/academic/langfuse-observability-llm-pipelines.md +0 -144
- package/articles/academic/medicine-wheel-software-architecture.md +0 -163
- package/articles/academic/mmot-autonomous-agents.md +0 -156
- package/articles/academic/model-context-protocol-interagent.md +0 -161
- package/articles/academic/pde-prompt-decomposition.md +0 -186
- package/articles/academic/structural-tension-in-ai-agents.md +0 -134
- package/articles/reviews/mcp-protocol-design-review.md +0 -170
- package/articles/reviews/observability-ai-systems-review.md +0 -176
- package/articles/reviews/prompt-engineering-decomposition-review.md +0 -184
- package/articles/surveys/agent-orchestration-survey.md +0 -186
- package/articles/surveys/knowledge-graph-storage-survey.md +0 -204
- package/articles/surveys/structural-tension-methodology-survey.md +0 -154
- package/articles/technical/aws-sdk-v3-polly.md +0 -270
- package/articles/technical/commander-cli-framework.md +0 -262
- package/articles/technical/dotenv-config-patterns.md +0 -360
- package/articles/technical/ioredis-vs-redis.md +0 -142
- package/articles/technical/langfuse-js-sdk-vs-rest.md +0 -191
- package/articles/technical/mcp-sdk-typescript.md +0 -291
- package/articles/technical/octokit-github-api.md +0 -293
- package/articles/technical/openai-sdk-modern.md +0 -231
- package/articles/technical/yaml-parsing-node.md +0 -266
- package/articles/technical/zod-runtime-validation.md +0 -212
- package/coaiajs-langfuse-claude-plugin/.claude-plugin/marketplace.json +0 -16
- package/coaiajs-langfuse-claude-plugin/.claude-plugin/plugin.json +0 -10
- package/coaiajs-langfuse-claude-plugin/.mcp.json +0 -8
- package/coaiajs-langfuse-claude-plugin/README.md +0 -60
- package/mcp/config.ts +0 -225
- package/mcp/prompts.ts +0 -131
- package/mcp/resources.ts +0 -84
- package/mcp/server.ts +0 -519
- package/mcp/tools/coaiapy-tools.ts +0 -366
- package/mcp/tools/index.ts +0 -4
- package/src/audio.ts +0 -76
- package/src/cli-helpers.ts +0 -86
- package/src/cli.ts +0 -1261
- package/src/config.ts +0 -207
- package/src/environment.ts +0 -171
- package/src/github.ts +0 -143
- package/src/index.ts +0 -82
- package/src/langfuse/client.ts +0 -105
- package/src/langfuse/comments.ts +0 -52
- package/src/langfuse/datasets.ts +0 -178
- package/src/langfuse/index.ts +0 -37
- package/src/langfuse/media.ts +0 -193
- package/src/langfuse/observations.ts +0 -155
- package/src/langfuse/prompts.ts +0 -157
- package/src/langfuse/scores.ts +0 -456
- package/src/langfuse/traces.ts +0 -353
- package/src/llm.ts +0 -106
- package/src/narrative/graph-manager.ts +0 -1358
- package/src/narrative/index.ts +0 -188
- package/src/narrative/markdown-export.ts +0 -535
- package/src/narrative/tool-definitions.ts +0 -635
- package/src/narrative/tool-handlers.ts +0 -528
- package/src/narrative/types.ts +0 -9
- package/src/narrative/validation.ts +0 -179
- package/src/pde/index.ts +0 -34
- package/src/pde/mcp-handlers.ts +0 -359
- package/src/pde/mcp-tools.ts +0 -201
- package/src/pde/session-manager.ts +0 -248
- package/src/pde/stc-mapper.ts +0 -298
- package/src/pipeline/index.ts +0 -7
- package/src/pipeline/template-engine.ts +0 -398
- package/src/planning/index.ts +0 -32
- package/src/planning/mcp-handlers.ts +0 -369
- package/src/planning/mcp-tools.ts +0 -155
- package/src/planning/plan-parser.ts +0 -587
- package/src/redis.ts +0 -111
- package/src/types.ts +0 -281
- package/src/version.ts +0 -39
- package/test/config.test.mjs +0 -93
- package/tsconfig.json +0 -26
package/llms-full.txt
ADDED
|
@@ -0,0 +1,361 @@
|
|
|
1
|
+
# coaiajs — Full Reference
|
|
2
|
+
|
|
3
|
+
> Complete API surface for `coaiajs`: every entry point, every export, all 63 MCP tools, and the full CLI. Written for AI agents integrating against this package.
|
|
4
|
+
|
|
5
|
+
Package: `coaiajs` · License: MIT · Node.js >= 20 · **ESM only**
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## 1. Orientation
|
|
10
|
+
|
|
11
|
+
`coaiajs` is the TypeScript consolidation of four CoAIA projects — `coaia-narrative` (knowledge graph, charts), `coaia-pde` (Prompt Decomposition Engine), `coaia-planning` (action planning), and `coaiapy` (Redis/LLM/audio/GitHub/config). It is consumable three ways, all sharing the same modules and the same type system (`src/types.ts`):
|
|
12
|
+
|
|
13
|
+
1. **Library** — `import { ... } from 'coaiajs'`
|
|
14
|
+
2. **CLI** — `npx coaia <command>`
|
|
15
|
+
3. **MCP server** — `npx coaiajs-mcp` (stdio)
|
|
16
|
+
|
|
17
|
+
### Central concept: the structural tension chart
|
|
18
|
+
|
|
19
|
+
The core data model comes from Robert Fritz's creative process framework. A chart holds three parts:
|
|
20
|
+
|
|
21
|
+
- **Desired Outcome** — what is to be created
|
|
22
|
+
- **Current Reality** — an honest assessment of where things stand
|
|
23
|
+
- **Action Steps** — steps holding the tension between the two; any step can *telescope* into its own sub-chart
|
|
24
|
+
|
|
25
|
+
Charts are stored as JSONL entities in a knowledge graph. "MMOT" (Managerial Moment of Truth) is a structured evaluation over a chart: acknowledge → analyze → plan → recommit.
|
|
26
|
+
|
|
27
|
+
### Rules that prevent the common mistakes
|
|
28
|
+
|
|
29
|
+
- **ESM only.** `require('coaiajs')` fails. Use `import`. The package sets `"type": "module"`.
|
|
30
|
+
- **Never import `coaiajs/src/...`.** `src/` is not in the published tarball. Use the documented subpaths. (Older documentation showed `coaiajs/src/redis.js`; that path has never resolved from an installed package.)
|
|
31
|
+
- **No side effects at import.** Importing opens no connection and reads no file. Clients are constructed on first use.
|
|
32
|
+
- **Close what you open.** `disconnect()` on Redis; `resetClient()` on any module to drop cached client state (primarily for tests).
|
|
33
|
+
|
|
34
|
+
---
|
|
35
|
+
|
|
36
|
+
## 2. Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install coaiajs
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
```typescript
|
|
43
|
+
import { tash, fetch, narrative } from 'coaiajs';
|
|
44
|
+
import { parsePlan } from 'coaiajs/planning';
|
|
45
|
+
import type { StructuralTensionPlan, Entity, CoaiaConfig } from 'coaiajs';
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
TypeScript consumers should use `"module": "NodeNext"` and `"moduleResolution": "NodeNext"` so the `exports` map and its `.d.ts` files resolve correctly.
|
|
49
|
+
|
|
50
|
+
---
|
|
51
|
+
|
|
52
|
+
## 3. Library API
|
|
53
|
+
|
|
54
|
+
Root import exposes everything below plus five namespaces (`langfuse`, `narrative`, `pde`, `planning`, `pipeline`) and 26 shared types. A subpath import and its root namespace are the same module.
|
|
55
|
+
|
|
56
|
+
### `coaiajs/config`
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
readConfig, getConfig, resetConfig, config, mergeConfigs, findExistingConfig, findEnvFiles
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
Resolution order (highest wins): environment variables → `.env` files (explicit `--env`, `COAIAJS_ENV_PATH`, `COAIAPY_ENV_PATH`, `./.env`, `~/.coaia/.env`) → `coaia.json` (`./coaia.json`, `~/coaia.json`, `~/.coaia/config.json`) → defaults.
|
|
63
|
+
|
|
64
|
+
### `coaiajs/redis`
|
|
65
|
+
|
|
66
|
+
```
|
|
67
|
+
tash, fetch, del, keys, exists, disconnect, getClient, resetClient
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
`tash`/`fetch` are SET/GET shorthand carried over from coaiapy. TTL is expressed in **minutes** at the CLI layer (default `5555`).
|
|
71
|
+
|
|
72
|
+
```typescript
|
|
73
|
+
import { tash, fetch, disconnect } from 'coaiajs/redis';
|
|
74
|
+
await tash('session:42', JSON.stringify({ phase: 'design' }));
|
|
75
|
+
const raw = await fetch('session:42');
|
|
76
|
+
await disconnect();
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
### `coaiajs/llm`
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
llm, transcribeAudio, generateImage, abstractProcess, resetClient
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
OpenAI-backed. `abstractProcess` applies a named tag/template to text; `transcribeAudio` uses Whisper.
|
|
86
|
+
|
|
87
|
+
### `coaiajs/audio`
|
|
88
|
+
|
|
89
|
+
```
|
|
90
|
+
synthesize, resetClient
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
AWS Polly text-to-speech.
|
|
94
|
+
|
|
95
|
+
### `coaiajs/github`
|
|
96
|
+
|
|
97
|
+
```
|
|
98
|
+
listIssues, getIssue, getIssueComments, resetClient
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Octokit-backed; reads `GITHUB_TOKEN`.
|
|
102
|
+
|
|
103
|
+
### `coaiajs/environment`
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
EnvironmentManager, createEnvironment, findEnvironment
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### `coaiajs/version`
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
getPackageVersion
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Returns the resolved version of the installed package, read from `package.json` at runtime.
|
|
116
|
+
|
|
117
|
+
### `coaiajs/narrative`
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
KnowledgeGraphManager, ValidationSchemas, validate,
|
|
121
|
+
addAction, completeAction, addObservation, setDueDate, setCurrentChart, getCurrentChart,
|
|
122
|
+
updateChart, viewChart, listCharts, getProgress, getStats, performMmot,
|
|
123
|
+
exportChart, exportAllCharts, exportChartToMarkdown, exportAllChartsToMarkdown,
|
|
124
|
+
exportChartProgress, exportChartStats, writeMarkdownToFile, getDefaultFilename,
|
|
125
|
+
handleToolCall, ALL_TOOL_DEFINITIONS, CORE_TOOLS, KG_TOOLS, NARRATIVE_TOOLS, STC_TOOLS
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
```typescript
|
|
129
|
+
import { KnowledgeGraphManager } from 'coaiajs/narrative';
|
|
130
|
+
const kg = new KnowledgeGraphManager('./memory.jsonl');
|
|
131
|
+
const graph = await kg.readGraph();
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### `coaiajs/pde`
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
SessionManager, sessionManager, StcMapper, stcMapper,
|
|
138
|
+
importDecomposition, listDecompositions, listSessions, showSession,
|
|
139
|
+
handlePdeTool, PDE_MCP_TOOLS
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### `coaiajs/planning`
|
|
143
|
+
|
|
144
|
+
```
|
|
145
|
+
parsePlan, parsePlanContent, planToSTC, convertToChart, decompositionResultToPlan,
|
|
146
|
+
syncToChart, syncToPlan, exportToJSONL, handlePlanningTool, PLANNING_MCP_TOOLS
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
```typescript
|
|
150
|
+
import { parsePlan, planToSTC } from 'coaiajs/planning';
|
|
151
|
+
const plan = await parsePlan('./PLAN.md');
|
|
152
|
+
const chart = planToSTC(plan);
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
### `coaiajs/pipeline`
|
|
156
|
+
|
|
157
|
+
```
|
|
158
|
+
MobileTemplateEngine, TemplateLoader, TemplateRenderer
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
### `coaiajs/langfuse`
|
|
162
|
+
|
|
163
|
+
Client and errors: `LangfuseClient`, `LangfuseApiError`, `getClient`, `resetClient`, `nowISO`, `detectContentType`
|
|
164
|
+
|
|
165
|
+
- **Traces:** `createTrace`, `addTrace`, `getTrace`, `listTraces`, `patchTraceOutput`, `traceView`, `sessionView`
|
|
166
|
+
- **Observations:** `addObservation`, `addObservations`, `getObservation`
|
|
167
|
+
- **Prompts:** `createPrompt`, `getPrompt`, `listPrompts`
|
|
168
|
+
- **Datasets:** `createDataset`, `getDataset`, `listDatasets`, `createDatasetItem`, `listDatasetItems`
|
|
169
|
+
- **Scores:** `createScore`, `listScores`, `createScoreForTarget`, `applyScoreToTrace`, `createScoreConfig`, `getScoreConfig`, `listScoreConfigs`, `applyScoreConfig`, `importScoreConfigs`, `exportScoreConfigs`, `getBuiltInPresets`, `installPreset`
|
|
170
|
+
- **Comments:** `createComment`, `getComment`, `listComments`
|
|
171
|
+
- **Media:** `uploadAndAttachMedia`, `getMedia`
|
|
172
|
+
- **Formatters:** `formatTracesTable`, `formatTracesMarkdown`, `formatTraceTree`, `formatObservationDisplay`, `formatPromptDisplay`, `formatPromptsTable`, `formatDatasetsTable`, `formatDatasetForFinetuning`, `formatScoresTable`, `formatScoreConfigsTable`, `formatMediaDisplay`
|
|
173
|
+
|
|
174
|
+
### Exported types
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
Entity, EntityMetadata, Relation, RelationMetadata, KnowledgeGraph, McpToolResult,
|
|
178
|
+
PrimaryIntent, SecondaryIntent, ContextRequirements, ExpectedOutputs,
|
|
179
|
+
DirectionItem, DirectionMap, ActionItem, AmbiguityFlag,
|
|
180
|
+
DecompositionResult, StoredDecomposition, DecompositionOptions, PdeSession,
|
|
181
|
+
StructuralElement, StructuralTensionPlan,
|
|
182
|
+
ScoreCategory, ScoreConfig,
|
|
183
|
+
PipelineVariable, PipelineStep, PipelineTemplate, CoaiaConfig
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
---
|
|
187
|
+
|
|
188
|
+
## 4. MCP Server
|
|
189
|
+
|
|
190
|
+
```bash
|
|
191
|
+
npx coaiajs-mcp
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Transport: **stdio**. Serves **63 tools, 3 prompts, 1 listable resource**.
|
|
195
|
+
|
|
196
|
+
Flags: `--memory-path <path>` (JSONL knowledge graph), `--plans-dir <path>`, `--feature-level <level>`.
|
|
197
|
+
|
|
198
|
+
Claude Code / client registration:
|
|
199
|
+
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"mcpServers": {
|
|
203
|
+
"coaia": { "command": "npx", "args": ["-y", "--package=coaiajs", "coaiajs-mcp"] }
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
### Feature levels
|
|
209
|
+
|
|
210
|
+
`COAIAJS_FEATURES` selects the exposed tool set; default `STANDARD`.
|
|
211
|
+
|
|
212
|
+
| Level | Effect |
|
|
213
|
+
|---|---|
|
|
214
|
+
| `MINIMAL` | Core tash/fetch and essential graph tools |
|
|
215
|
+
| `STANDARD` | Default — the 63 tools listed below |
|
|
216
|
+
| `OBSERVABILITY` | Same set as `STANDARD` |
|
|
217
|
+
| `FULL` | Everything, including media tools |
|
|
218
|
+
|
|
219
|
+
### Tools — coaiapy + Langfuse (20)
|
|
220
|
+
|
|
221
|
+
```
|
|
222
|
+
coaia_tash, coaia_fetch,
|
|
223
|
+
coaia_fuse_trace_create, coaia_fuse_add_observation, coaia_fuse_trace_patch_output,
|
|
224
|
+
coaia_fuse_trace_get, coaia_fuse_trace_view, coaia_fuse_observation_get,
|
|
225
|
+
coaia_fuse_traces_list, coaia_fuse_traces_session_view,
|
|
226
|
+
coaia_fuse_prompts_list, coaia_fuse_prompts_get,
|
|
227
|
+
coaia_fuse_datasets_list, coaia_fuse_datasets_get,
|
|
228
|
+
coaia_fuse_score_configs_list, coaia_fuse_score_configs_get, coaia_fuse_score_apply,
|
|
229
|
+
coaia_fuse_comments_list, coaia_fuse_comments_get, coaia_fuse_comments_create
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
### Tools — narrative / knowledge graph (27)
|
|
233
|
+
|
|
234
|
+
```
|
|
235
|
+
create_entities, create_relations, add_observations,
|
|
236
|
+
delete_entities, delete_observations, delete_relations,
|
|
237
|
+
read_graph, search_nodes, open_nodes,
|
|
238
|
+
create_structural_tension_chart, manage_action_step, add_action_step,
|
|
239
|
+
telescope_action_step, remove_action_step, mark_action_complete,
|
|
240
|
+
get_chart_progress, list_active_charts, get_chart, get_action_step,
|
|
241
|
+
update_action_progress, update_current_reality, update_desired_outcome,
|
|
242
|
+
perform_mmot_evaluation,
|
|
243
|
+
create_narrative_beat, telescope_narrative_beat, list_narrative_beats,
|
|
244
|
+
init_llm_guidance
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
### Tools — PDE (10)
|
|
248
|
+
|
|
249
|
+
```
|
|
250
|
+
import_pde_decomposition, create_stc_from_pde, list_pde_decompositions,
|
|
251
|
+
get_session, list_sessions, complete_session,
|
|
252
|
+
pde_update_action_progress, pde_mark_action_complete,
|
|
253
|
+
pde_add_action_step, pde_update_current_reality
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
The last four carry a `pde_` prefix because their unprefixed names belong to the narrative group. Calling `add_action_step` targets the narrative chart; `pde_add_action_step` targets the PDE session.
|
|
257
|
+
|
|
258
|
+
### Tools — planning (6)
|
|
259
|
+
|
|
260
|
+
```
|
|
261
|
+
parse_plan_structural, plan_to_stc, sync_plan_to_chart,
|
|
262
|
+
sync_chart_to_plan, create_plan_trace, pde_to_plan
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Prompts (3)
|
|
266
|
+
|
|
267
|
+
- `mia_miette_duo` — dual AI embodiment for narrative-driven technical work
|
|
268
|
+
- `create_observability_pipeline` — step-by-step guide for creating a Langfuse observability pipeline
|
|
269
|
+
- `analyze_audio_workflow` — workflow for audio analysis
|
|
270
|
+
|
|
271
|
+
### Resources
|
|
272
|
+
|
|
273
|
+
- `coaia://templates/` — listable; returns all pipeline templates
|
|
274
|
+
- `coaia://templates/{name}` — readable URI pattern; a single template
|
|
275
|
+
- `coaia://templates/{name}/variables` — readable URI pattern; a template's variables
|
|
276
|
+
|
|
277
|
+
### Error convention
|
|
278
|
+
|
|
279
|
+
Tool failures return a normal result with `isError: true` and a text explanation rather than a JSON-RPC error. An unknown tool name yields `Unknown tool: <name>`.
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
## 5. CLI
|
|
284
|
+
|
|
285
|
+
```bash
|
|
286
|
+
npx coaia <command>
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
Global options: `--env <path>` · `-M, --memory-path <path>` · `--json` · `--no-color` · `-V, --version` · `-h, --help`
|
|
290
|
+
|
|
291
|
+
| Command | Aliases | Purpose |
|
|
292
|
+
|---|---|---|
|
|
293
|
+
| `tash <key> [value]` | `m` | Store a key-value pair in Redis. `-F/--file` reads value from a file; `-T/--ttl` in minutes (default 5555) |
|
|
294
|
+
| `fetch <key>` | | Get a value from Redis |
|
|
295
|
+
| `llm <user> [system]` | | Raw LLM call |
|
|
296
|
+
| `summarize [text]` | `s` | Summarize text |
|
|
297
|
+
| `transcribe <file>` | `t` | Transcribe audio via Whisper |
|
|
298
|
+
| `p <tag> [text]` | | Process text with a custom tag |
|
|
299
|
+
| `init` | | Create a sample `coaia.json` |
|
|
300
|
+
| `fuse` | | Langfuse operations |
|
|
301
|
+
| `narrative` | `n` | Structural tension chart operations |
|
|
302
|
+
| `pde` | | Prompt Decomposition Engine |
|
|
303
|
+
| `plan` | | Structural tension plan operations |
|
|
304
|
+
| `pipeline` | | Pipeline template operations |
|
|
305
|
+
| `env` | | Environment variable management |
|
|
306
|
+
| `gh` | | GitHub operations |
|
|
307
|
+
|
|
308
|
+
Subcommands:
|
|
309
|
+
|
|
310
|
+
- **`fuse`** — `traces`, `prompts`, `datasets`, `sessions`, `scores` (`sc`), `score-configs` (`scc`), `comments`, `media`, `dataset-items`, `projects`
|
|
311
|
+
- **`narrative`** — `list` (`ls`), `view` (`v`), `current` (`cur`), `update` (`up`), `add-action` (`aa`), `add-obs` (`ao`), `complete` (`done`), `export` (`exp`), `export-all`, `stats` (`st`), `progress` (`pg`), `mmot`, `set-date` (`sd`)
|
|
312
|
+
- **`pde`** — `import <pdeId>`, `list`, `sessions`, `show <sessionId>`
|
|
313
|
+
- **`plan`** — `parse <planPath>`, `convert <planPath>`, `sync-to-chart <planPath> <chartsPath>`, `sync-to-plan <chartsPath> <planPath>`
|
|
314
|
+
- **`pipeline`** — `list`, `show <name>`, `create <name>`, `init <name>`
|
|
315
|
+
- **`env`** — `init`, `list`, `source`, `set <key> <value>`, `get <key>`, `unset <key>`, `clear`, `save`
|
|
316
|
+
- **`gh`** — `issues`
|
|
317
|
+
|
|
318
|
+
---
|
|
319
|
+
|
|
320
|
+
## 6. Configuration reference
|
|
321
|
+
|
|
322
|
+
| Variable | Description |
|
|
323
|
+
|---|---|
|
|
324
|
+
| `UPSTASH_REDIS_REST_URL` / `UPSTASH_REDIS_REST_TOKEN` | Upstash Redis endpoint and token; preferred over direct Redis URLs |
|
|
325
|
+
| `KV_REST_API_URL` / `KV_REST_API_TOKEN` | Vercel KV REST aliases for Upstash Redis |
|
|
326
|
+
| `KV_URL` / `REDIS_URL` | Redis connection URL (`redis://` or `rediss://`) |
|
|
327
|
+
| `REDIS_HOST` / `REDIS_PORT` / `REDIS_PASSWORD` / `REDIS_SSL` | Traditional Redis configuration |
|
|
328
|
+
| `UPSTASH_HOST` / `UPSTASH_PASSWORD` | coaiapy-compatible fallback aliases |
|
|
329
|
+
| `OPENAI_API_KEY` | OpenAI API key |
|
|
330
|
+
| `LANGFUSE_PUBLIC_KEY` / `LANGFUSE_SECRET_KEY` | Langfuse credentials |
|
|
331
|
+
| `AWS_ACCESS_KEY_ID` | AWS credentials for Polly |
|
|
332
|
+
| `GITHUB_TOKEN` | GitHub API token |
|
|
333
|
+
| `COAIAJS_ENV_PATH` / `COAIAPY_ENV_PATH` | Explicit `.env` file locations |
|
|
334
|
+
| `COAIAJS_FEATURES` | MCP feature level |
|
|
335
|
+
|
|
336
|
+
`coaia.json`:
|
|
337
|
+
|
|
338
|
+
```json
|
|
339
|
+
{
|
|
340
|
+
"redis": { "url": "redis://localhost:6379" },
|
|
341
|
+
"openai": { "apiKey": "sk-...", "model": "gpt-4o" },
|
|
342
|
+
"langfuse": { "publicKey": "pk-...", "secretKey": "sk-..." },
|
|
343
|
+
"github": { "token": "ghp_..." }
|
|
344
|
+
}
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
---
|
|
348
|
+
|
|
349
|
+
## 7. Working on this codebase
|
|
350
|
+
|
|
351
|
+
```bash
|
|
352
|
+
npm install
|
|
353
|
+
npm run build # tsc
|
|
354
|
+
npm run lint # tsc --noEmit
|
|
355
|
+
npm test # node --test
|
|
356
|
+
npm run dev # tsc --watch
|
|
357
|
+
```
|
|
358
|
+
|
|
359
|
+
Conventions: ESM only, relative imports end in `.js` · `strict: true`, no unjustified `any` · shared types live in `src/types.ts` · clients lazy, each module exports `resetClient()` · no side effects at import time.
|
|
360
|
+
|
|
361
|
+
Per-module RISE specifications live in `rispecs/`, one file per module.
|
package/llms.txt
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
# coaiajs
|
|
2
|
+
|
|
3
|
+
> TypeScript package consolidating the CoAIA (Creative Orientation AI Architecture) ecosystem into one installable unit: a **library**, a **CLI** (`coaia`), and an **MCP server** (`coaiajs-mcp`, 63 tools). Its core data model is the *structural tension chart* — desired outcome, current reality, and telescoping action steps — backed by a JSONL knowledge graph.
|
|
4
|
+
|
|
5
|
+
Install with `npm install coaiajs`. Requires Node.js >= 20. **ESM only** — there is no CommonJS build, so `require('coaiajs')` will not work. Ships `.d.ts` for every entry point.
|
|
6
|
+
|
|
7
|
+
Key facts an agent usually needs first:
|
|
8
|
+
|
|
9
|
+
- Import from `coaiajs` (root) or a subpath such as `coaiajs/narrative`. **Do not** import `coaiajs/src/*.js` — `src/` is not shipped in the published package.
|
|
10
|
+
- Clients (Redis, OpenAI, Polly, Octokit) are lazy: importing a module opens no connection and reads no file. Call `disconnect()` when finished.
|
|
11
|
+
- Config precedence: environment variables > `.env` files > `coaia.json` > defaults.
|
|
12
|
+
- The MCP server serves 63 tools, 3 prompts, and 1 listable resource over stdio. `COAIAJS_FEATURES` (`MINIMAL`/`STANDARD`/`OBSERVABILITY`/`FULL`) controls the tool set; default is `STANDARD`.
|
|
13
|
+
|
|
14
|
+
## Documentation
|
|
15
|
+
|
|
16
|
+
- [README](./README.md): install, the three consumption modes, configuration, architecture
|
|
17
|
+
- [llms-full.txt](./llms-full.txt): complete API surface — every export, every MCP tool, every CLI command, in one file
|
|
18
|
+
- [CLAUDE.md](./CLAUDE.md): repository conventions for agents working *on* this codebase
|
|
19
|
+
- [KINSHIP.md](./KINSHIP.md): lineage and type provenance from the four origin projects
|
|
20
|
+
|
|
21
|
+
## Entry points
|
|
22
|
+
|
|
23
|
+
- `coaiajs`: everything, plus `langfuse`/`narrative`/`pde`/`planning`/`pipeline` namespaces and shared types
|
|
24
|
+
- `coaiajs/config`: configuration resolution — `readConfig`, `getConfig`, `resetConfig`
|
|
25
|
+
- `coaiajs/redis`: `tash`, `fetch`, `del`, `keys`, `exists`, `disconnect`
|
|
26
|
+
- `coaiajs/llm`: `llm`, `transcribeAudio`, `generateImage`, `abstractProcess`
|
|
27
|
+
- `coaiajs/audio`: `synthesize` (AWS Polly)
|
|
28
|
+
- `coaiajs/github`: `listIssues`, `getIssue`, `getIssueComments`
|
|
29
|
+
- `coaiajs/environment`: `EnvironmentManager`, `createEnvironment`, `findEnvironment`
|
|
30
|
+
- `coaiajs/version`: `getPackageVersion`
|
|
31
|
+
- `coaiajs/langfuse`: tracing, observations, prompts, datasets, scores, comments, media
|
|
32
|
+
- `coaiajs/narrative`: `KnowledgeGraphManager`, structural tension charts, markdown export
|
|
33
|
+
- `coaiajs/pde`: Prompt Decomposition Engine — sessions, STC mapping
|
|
34
|
+
- `coaiajs/planning`: `parsePlan`, `planToSTC`, `syncToChart`, `syncToPlan`
|
|
35
|
+
- `coaiajs/pipeline`: pipeline template engine
|
|
36
|
+
|
|
37
|
+
## Specifications
|
|
38
|
+
|
|
39
|
+
- [rispecs/](./rispecs/): RISE specification files, one per module (config, redis, langfuse, narrative, PDE, planning, pipeline, CLI, MCP, audio)
|
|
40
|
+
|
|
41
|
+
## Optional
|
|
42
|
+
|
|
43
|
+
- [Claude Code plugin](./coaiajs-langfuse-claude-plugin/): registers the MCP server in Claude Code via `npx`
|
package/package.json
CHANGED
|
@@ -1,8 +1,74 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "coaiajs",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.2",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"description": "CoAIA unified TypeScript monorepo — CLI, MCP server, and library consolidating coaia-narrative, coaia-pde, coaia-planning, and coaiapy patterns into one package.",
|
|
6
|
+
"main": "./dist/src/index.js",
|
|
7
|
+
"types": "./dist/src/index.d.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/src/index.d.ts",
|
|
11
|
+
"import": "./dist/src/index.js"
|
|
12
|
+
},
|
|
13
|
+
"./config": {
|
|
14
|
+
"types": "./dist/src/config.d.ts",
|
|
15
|
+
"import": "./dist/src/config.js"
|
|
16
|
+
},
|
|
17
|
+
"./redis": {
|
|
18
|
+
"types": "./dist/src/redis.d.ts",
|
|
19
|
+
"import": "./dist/src/redis.js"
|
|
20
|
+
},
|
|
21
|
+
"./llm": {
|
|
22
|
+
"types": "./dist/src/llm.d.ts",
|
|
23
|
+
"import": "./dist/src/llm.js"
|
|
24
|
+
},
|
|
25
|
+
"./audio": {
|
|
26
|
+
"types": "./dist/src/audio.d.ts",
|
|
27
|
+
"import": "./dist/src/audio.js"
|
|
28
|
+
},
|
|
29
|
+
"./github": {
|
|
30
|
+
"types": "./dist/src/github.d.ts",
|
|
31
|
+
"import": "./dist/src/github.js"
|
|
32
|
+
},
|
|
33
|
+
"./environment": {
|
|
34
|
+
"types": "./dist/src/environment.d.ts",
|
|
35
|
+
"import": "./dist/src/environment.js"
|
|
36
|
+
},
|
|
37
|
+
"./version": {
|
|
38
|
+
"types": "./dist/src/version.d.ts",
|
|
39
|
+
"import": "./dist/src/version.js"
|
|
40
|
+
},
|
|
41
|
+
"./langfuse": {
|
|
42
|
+
"types": "./dist/src/langfuse/index.d.ts",
|
|
43
|
+
"import": "./dist/src/langfuse/index.js"
|
|
44
|
+
},
|
|
45
|
+
"./narrative": {
|
|
46
|
+
"types": "./dist/src/narrative/index.d.ts",
|
|
47
|
+
"import": "./dist/src/narrative/index.js"
|
|
48
|
+
},
|
|
49
|
+
"./pde": {
|
|
50
|
+
"types": "./dist/src/pde/index.d.ts",
|
|
51
|
+
"import": "./dist/src/pde/index.js"
|
|
52
|
+
},
|
|
53
|
+
"./planning": {
|
|
54
|
+
"types": "./dist/src/planning/index.d.ts",
|
|
55
|
+
"import": "./dist/src/planning/index.js"
|
|
56
|
+
},
|
|
57
|
+
"./pipeline": {
|
|
58
|
+
"types": "./dist/src/pipeline/index.d.ts",
|
|
59
|
+
"import": "./dist/src/pipeline/index.js"
|
|
60
|
+
},
|
|
61
|
+
"./package.json": "./package.json"
|
|
62
|
+
},
|
|
63
|
+
"files": [
|
|
64
|
+
"dist",
|
|
65
|
+
"rispecs",
|
|
66
|
+
"README.md",
|
|
67
|
+
"KINSHIP.md",
|
|
68
|
+
"CLAUDE.md",
|
|
69
|
+
"llms.txt",
|
|
70
|
+
"llms-full.txt"
|
|
71
|
+
],
|
|
6
72
|
"bin": {
|
|
7
73
|
"coaia": "dist/src/cli.js",
|
|
8
74
|
"coaiajs-mcp": "dist/mcp/server.js"
|
|
@@ -15,28 +81,29 @@
|
|
|
15
81
|
"dev": "tsc --watch",
|
|
16
82
|
"start": "node dist/src/cli.js",
|
|
17
83
|
"mcp": "node dist/mcp/server.js",
|
|
84
|
+
"pretest": "tsc",
|
|
18
85
|
"test": "node --test",
|
|
19
86
|
"lint": "tsc --noEmit"
|
|
20
87
|
},
|
|
21
88
|
"dependencies": {
|
|
22
|
-
"@
|
|
23
|
-
"
|
|
24
|
-
"
|
|
89
|
+
"@aws-sdk/client-polly": "^3.1117.0",
|
|
90
|
+
"@modelcontextprotocol/sdk": "^1.30.0",
|
|
91
|
+
"@octokit/rest": "^21.1.1",
|
|
92
|
+
"chalk": "^5.6.2",
|
|
25
93
|
"commander": "^12.1.0",
|
|
26
|
-
"
|
|
27
|
-
"
|
|
28
|
-
"@octokit/rest": "^21.0.0",
|
|
29
|
-
"dotenv": "^16.4.0",
|
|
94
|
+
"dotenv": "^16.6.1",
|
|
95
|
+
"ioredis": "^5.11.1",
|
|
30
96
|
"js-yaml": "^4.1.0",
|
|
31
|
-
"langfuse": "^3.
|
|
97
|
+
"langfuse": "^3.38.20",
|
|
32
98
|
"minimist": "^1.2.8",
|
|
33
|
-
"
|
|
34
|
-
"uuid": "^11.1.
|
|
99
|
+
"openai": "^4.104.0",
|
|
100
|
+
"uuid": "^11.1.1",
|
|
101
|
+
"zod": "^3.25.76"
|
|
35
102
|
},
|
|
36
103
|
"devDependencies": {
|
|
37
|
-
"@types/node": "^22.0.0",
|
|
38
104
|
"@types/js-yaml": "^4.0.9",
|
|
39
105
|
"@types/minimist": "^1.2.5",
|
|
106
|
+
"@types/node": "^22.0.0",
|
|
40
107
|
"@types/uuid": "^10.0.0",
|
|
41
108
|
"typescript": "^5.7.0"
|
|
42
109
|
},
|
|
@@ -1,17 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"permissions": {
|
|
3
|
-
"allow": [
|
|
4
|
-
"mcp__claude_ai_Notion__notion-create-pages",
|
|
5
|
-
"Bash(git add *)",
|
|
6
|
-
"Bash(git config *)",
|
|
7
|
-
"Bash(git commit *)",
|
|
8
|
-
"Bash(gh issue *)",
|
|
9
|
-
"Bash(git rebase *)",
|
|
10
|
-
"Bash(git push *)"
|
|
11
|
-
],
|
|
12
|
-
"additionalDirectories": [
|
|
13
|
-
"/src/coaiapy",
|
|
14
|
-
"/workspace/repos/jgwill/miadi-orchestration-kit"
|
|
15
|
-
]
|
|
16
|
-
}
|
|
17
|
-
}
|
|
@@ -1,26 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "coaiajs-marketplace",
|
|
3
|
-
"owner": {
|
|
4
|
-
"name": "Guillaume Isabelle",
|
|
5
|
-
"email": "jgi@jgwill.com",
|
|
6
|
-
"url": "https://github.com/jgwill"
|
|
7
|
-
},
|
|
8
|
-
"metadata": {
|
|
9
|
-
"description": "CoAIA Claude Code plugins",
|
|
10
|
-
"version": "0.3.0"
|
|
11
|
-
},
|
|
12
|
-
"plugins": [
|
|
13
|
-
{
|
|
14
|
-
"name": "coaiajs-langfuse",
|
|
15
|
-
"source": "./coaiajs-langfuse-claude-plugin",
|
|
16
|
-
"description": "CoAIA unified MCP — 64+ tools (structural tension charts, narrative knowledge graph, PDE, planning, Redis tash/fetch, Langfuse tracing).",
|
|
17
|
-
"version": "0.3.0",
|
|
18
|
-
"author": {
|
|
19
|
-
"name": "Guillaume Isabelle",
|
|
20
|
-
"url": "https://github.com/jgwill"
|
|
21
|
-
},
|
|
22
|
-
"license": "MIT",
|
|
23
|
-
"keywords": ["coaia", "mcp", "structural-tension", "narrative", "pde", "planning", "langfuse"]
|
|
24
|
-
}
|
|
25
|
-
]
|
|
26
|
-
}
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
These article were written by AI
|
|
@@ -1 +0,0 @@
|
|
|
1
|
-
These article were written by AI
|