cognitive-modules 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl
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.
- cognitive/__init__.py +1 -1
- cognitive/loader.py +17 -6
- cognitive/migrate.py +9 -3
- cognitive/runner.py +578 -28
- cognitive_modules-0.6.0.dist-info/METADATA +615 -0
- {cognitive_modules-0.5.0.dist-info → cognitive_modules-0.6.0.dist-info}/RECORD +10 -10
- cognitive_modules-0.5.0.dist-info/METADATA +0 -431
- {cognitive_modules-0.5.0.dist-info → cognitive_modules-0.6.0.dist-info}/WHEEL +0 -0
- {cognitive_modules-0.5.0.dist-info → cognitive_modules-0.6.0.dist-info}/entry_points.txt +0 -0
- {cognitive_modules-0.5.0.dist-info → cognitive_modules-0.6.0.dist-info}/licenses/LICENSE +0 -0
- {cognitive_modules-0.5.0.dist-info → cognitive_modules-0.6.0.dist-info}/top_level.txt +0 -0
|
@@ -0,0 +1,615 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: cognitive-modules
|
|
3
|
+
Version: 0.6.0
|
|
4
|
+
Summary: Structured LLM task runner with schema validation, confidence scoring, and subagent orchestration
|
|
5
|
+
Author: ziel-io
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/ziel-io/cognitive-modules
|
|
8
|
+
Project-URL: Documentation, https://github.com/ziel-io/cognitive-modules#readme
|
|
9
|
+
Project-URL: Repository, https://github.com/ziel-io/cognitive-modules
|
|
10
|
+
Project-URL: Issues, https://github.com/ziel-io/cognitive-modules/issues
|
|
11
|
+
Keywords: llm,cognitive,modules,ai,cli,schema,validation,prompt,agent,subagent
|
|
12
|
+
Classifier: Development Status :: 4 - Beta
|
|
13
|
+
Classifier: Intended Audience :: Developers
|
|
14
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Programming Language :: Python :: 3
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
20
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
21
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
22
|
+
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
|
|
23
|
+
Requires-Python: >=3.9
|
|
24
|
+
Description-Content-Type: text/markdown
|
|
25
|
+
License-File: LICENSE
|
|
26
|
+
Requires-Dist: jsonschema>=4.17.0
|
|
27
|
+
Requires-Dist: pyyaml>=6.0
|
|
28
|
+
Requires-Dist: typer>=0.9.0
|
|
29
|
+
Requires-Dist: rich>=13.0.0
|
|
30
|
+
Provides-Extra: openai
|
|
31
|
+
Requires-Dist: openai>=1.0.0; extra == "openai"
|
|
32
|
+
Provides-Extra: anthropic
|
|
33
|
+
Requires-Dist: anthropic>=0.18.0; extra == "anthropic"
|
|
34
|
+
Provides-Extra: ollama
|
|
35
|
+
Requires-Dist: requests>=2.28.0; extra == "ollama"
|
|
36
|
+
Provides-Extra: minimax
|
|
37
|
+
Requires-Dist: openai>=1.0.0; extra == "minimax"
|
|
38
|
+
Provides-Extra: all
|
|
39
|
+
Requires-Dist: openai>=1.0.0; extra == "all"
|
|
40
|
+
Requires-Dist: anthropic>=0.18.0; extra == "all"
|
|
41
|
+
Requires-Dist: requests>=2.28.0; extra == "all"
|
|
42
|
+
Provides-Extra: server
|
|
43
|
+
Requires-Dist: fastapi>=0.109.0; extra == "server"
|
|
44
|
+
Requires-Dist: uvicorn[standard]>=0.27.0; extra == "server"
|
|
45
|
+
Requires-Dist: pydantic>=2.0.0; extra == "server"
|
|
46
|
+
Provides-Extra: mcp
|
|
47
|
+
Requires-Dist: mcp>=1.0.0; extra == "mcp"
|
|
48
|
+
Provides-Extra: dev
|
|
49
|
+
Requires-Dist: pytest>=7.0.0; extra == "dev"
|
|
50
|
+
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
|
|
51
|
+
Requires-Dist: build>=1.0.0; extra == "dev"
|
|
52
|
+
Requires-Dist: twine>=4.0.0; extra == "dev"
|
|
53
|
+
Requires-Dist: ruff>=0.1.0; extra == "dev"
|
|
54
|
+
Provides-Extra: docs
|
|
55
|
+
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
|
|
56
|
+
Requires-Dist: pymdown-extensions>=10.0.0; extra == "docs"
|
|
57
|
+
Dynamic: license-file
|
|
58
|
+
|
|
59
|
+
# Cognitive Modules
|
|
60
|
+
|
|
61
|
+
[](https://github.com/ziel-io/cognitive-modules/actions/workflows/ci.yml)
|
|
62
|
+
[](https://pypi.org/project/cognitive-modules/)
|
|
63
|
+
[](https://www.python.org/downloads/)
|
|
64
|
+
[](https://opensource.org/licenses/MIT)
|
|
65
|
+
|
|
66
|
+
> Verifiable Structured AI Task Specification
|
|
67
|
+
|
|
68
|
+
English | [中文](README_zh.md)
|
|
69
|
+
|
|
70
|
+
Cognitive Modules is an AI task definition specification designed for generation tasks that require **strong constraints, verifiability, and auditability**.
|
|
71
|
+
|
|
72
|
+
## What's New in v2.5
|
|
73
|
+
|
|
74
|
+
| Feature | Description |
|
|
75
|
+
|---------|-------------|
|
|
76
|
+
| **Streaming Response** | Real-time chunk-based output for better UX |
|
|
77
|
+
| **Multimodal Support** | Native image, audio, and video input/output |
|
|
78
|
+
| **Backward Compatible** | v2.2 modules run without modification |
|
|
79
|
+
| **Level 4 Conformance** | Extended conformance level for v2.5 features |
|
|
80
|
+
|
|
81
|
+
```yaml
|
|
82
|
+
# module.yaml - v2.5 example
|
|
83
|
+
name: image-analyzer
|
|
84
|
+
version: 2.5.0
|
|
85
|
+
tier: decision
|
|
86
|
+
|
|
87
|
+
# v2.5: Enable streaming
|
|
88
|
+
response:
|
|
89
|
+
mode: streaming
|
|
90
|
+
chunk_type: delta
|
|
91
|
+
|
|
92
|
+
# v2.5: Enable multimodal
|
|
93
|
+
modalities:
|
|
94
|
+
input: [text, image]
|
|
95
|
+
output: [text]
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## What's New in v2.2
|
|
99
|
+
|
|
100
|
+
| Feature | Description |
|
|
101
|
+
|---------|-------------|
|
|
102
|
+
| **Control/Data Separation** | `meta` control plane + `data` data plane, middleware can route without parsing business logic |
|
|
103
|
+
| **Module Tiers** | `exec` / `decision` / `exploration` with different strictness levels |
|
|
104
|
+
| **Recoverable Overflow** | `extensions.insights` preserves LLM's additional insights |
|
|
105
|
+
| **Extensible Enums** | Allow custom types without sacrificing type safety |
|
|
106
|
+
| **Repair Pass** | Auto-fix formatting issues, reduce validation failures |
|
|
107
|
+
|
|
108
|
+
## Features
|
|
109
|
+
|
|
110
|
+
- **Strong Type Contracts** - JSON Schema bidirectional validation for input/output
|
|
111
|
+
- **Explainable Output** - Mandatory `confidence` + `rationale` output
|
|
112
|
+
- **Control/Data Separation** - `meta.explain` for quick routing + `data.rationale` for detailed audit
|
|
113
|
+
- **Module Tiers** - exec / decision / exploration with different constraint levels
|
|
114
|
+
- **Subagent Orchestration** - `@call:module` supports inter-module calls
|
|
115
|
+
- **Parameter Passing** - `$ARGUMENTS` runtime substitution
|
|
116
|
+
- **Multi-LLM Support** - OpenAI / Anthropic / MiniMax / Ollama
|
|
117
|
+
- **Public Registry** - `cogn install registry:module-name`
|
|
118
|
+
|
|
119
|
+
## Installation
|
|
120
|
+
|
|
121
|
+
### Node.js (npm) - Recommended
|
|
122
|
+
|
|
123
|
+
```bash
|
|
124
|
+
# Zero-install quick start (recommended)
|
|
125
|
+
npx cogn run code-reviewer --args "your code"
|
|
126
|
+
|
|
127
|
+
# Global installation
|
|
128
|
+
npm install -g cogn
|
|
129
|
+
|
|
130
|
+
# Or install with full package name
|
|
131
|
+
npm install -g cognitive-modules-cli
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Python (pip)
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
pip install cognitive-modules
|
|
138
|
+
|
|
139
|
+
# With LLM support
|
|
140
|
+
pip install cognitive-modules[openai] # OpenAI
|
|
141
|
+
pip install cognitive-modules[anthropic] # Claude
|
|
142
|
+
pip install cognitive-modules[all] # All providers
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
| Platform | Package | Command | Features |
|
|
146
|
+
|----------|---------|---------|----------|
|
|
147
|
+
| **npm** | `cogn` | `cog` | ✅ Recommended, zero-install, full features |
|
|
148
|
+
| pip | `cognitive-modules` | `cogn` | ✅ Full features |
|
|
149
|
+
|
|
150
|
+
## Quick Start
|
|
151
|
+
|
|
152
|
+
```bash
|
|
153
|
+
# Configure LLM
|
|
154
|
+
export LLM_PROVIDER=openai
|
|
155
|
+
export OPENAI_API_KEY=sk-xxx
|
|
156
|
+
|
|
157
|
+
# Run code review (npm)
|
|
158
|
+
npx cogn run code-reviewer --args "def login(u,p): return db.query(f'SELECT * FROM users WHERE name={u}')" --pretty
|
|
159
|
+
|
|
160
|
+
# Or use globally installed cog command
|
|
161
|
+
cog run code-reviewer --args "..." --pretty
|
|
162
|
+
|
|
163
|
+
# Run task prioritization
|
|
164
|
+
cog run task-prioritizer --args "fix bug(urgent), write docs, optimize performance" --pretty
|
|
165
|
+
|
|
166
|
+
# Run API design
|
|
167
|
+
cog run api-designer --args "user system CRUD API" --pretty
|
|
168
|
+
|
|
169
|
+
# Start HTTP service (API integration)
|
|
170
|
+
cog serve --port 8000
|
|
171
|
+
|
|
172
|
+
# Start MCP server (Claude Code / Cursor integration)
|
|
173
|
+
cog mcp
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## v2.2 Response Format
|
|
177
|
+
|
|
178
|
+
All modules now return the unified v2.2 envelope format:
|
|
179
|
+
|
|
180
|
+
```json
|
|
181
|
+
{
|
|
182
|
+
"ok": true,
|
|
183
|
+
"meta": {
|
|
184
|
+
"confidence": 0.92,
|
|
185
|
+
"risk": "low",
|
|
186
|
+
"explain": "Brief summary for quick routing decisions (≤280 chars)"
|
|
187
|
+
},
|
|
188
|
+
"data": {
|
|
189
|
+
"...business fields...",
|
|
190
|
+
"rationale": "Detailed reasoning for audit and human review",
|
|
191
|
+
"extensions": {
|
|
192
|
+
"insights": [
|
|
193
|
+
{
|
|
194
|
+
"text": "Additional insight",
|
|
195
|
+
"suggested_mapping": "Suggested field to add to schema"
|
|
196
|
+
}
|
|
197
|
+
]
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
}
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
### Control vs Data Plane
|
|
204
|
+
|
|
205
|
+
| Layer | Field | Purpose |
|
|
206
|
+
|-------|-------|---------|
|
|
207
|
+
| **Control Plane** | `meta.confidence` | Routing/fallback decisions |
|
|
208
|
+
| **Control Plane** | `meta.risk` | Human review trigger |
|
|
209
|
+
| **Control Plane** | `meta.explain` | Logs/card UI |
|
|
210
|
+
| **Data Plane** | `data.rationale` | Detailed audit |
|
|
211
|
+
| **Data Plane** | `data.extensions` | Recoverable insights |
|
|
212
|
+
|
|
213
|
+
## Core Features
|
|
214
|
+
|
|
215
|
+
| Feature | Description |
|
|
216
|
+
|---------|-------------|
|
|
217
|
+
| **JSON Schema Validation** | Bidirectional input/output validation |
|
|
218
|
+
| **Confidence** | Every output must include 0-1 confidence |
|
|
219
|
+
| **Reasoning** | `meta.explain` (brief) + `data.rationale` (detailed) |
|
|
220
|
+
| **Module Tiers** | `tier: exec \| decision \| exploration` |
|
|
221
|
+
| **Risk Aggregation** | `meta.risk = max(changes[*].risk)` |
|
|
222
|
+
| **Parameter Passing** | `$ARGUMENTS` runtime substitution |
|
|
223
|
+
| **Subagents** | `@call:module` for inter-module calls |
|
|
224
|
+
| **Validation Tools** | `cogn validate` / `cogn validate --v22` |
|
|
225
|
+
|
|
226
|
+
## Integration Methods
|
|
227
|
+
|
|
228
|
+
| Method | Command | Use Case |
|
|
229
|
+
|--------|---------|----------|
|
|
230
|
+
| CLI | `cogn run` | Command line |
|
|
231
|
+
| HTTP API | `cogn serve` | n8n, Coze, Dify |
|
|
232
|
+
| MCP Server | `cogn mcp` | Claude, Cursor |
|
|
233
|
+
|
|
234
|
+
## CLI Commands
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
# Module management
|
|
238
|
+
cogn list # List installed modules
|
|
239
|
+
cogn info <module> # View module details
|
|
240
|
+
cogn validate <module> # Validate module structure
|
|
241
|
+
cogn validate <module> --v22 # Validate v2.2 format
|
|
242
|
+
|
|
243
|
+
# Run modules
|
|
244
|
+
cogn run <module> input.json -o output.json --pretty
|
|
245
|
+
cogn run <module> --args "requirements" --pretty
|
|
246
|
+
cogn run <module> --args "requirements" --subagent # Enable subagent
|
|
247
|
+
|
|
248
|
+
# Create modules
|
|
249
|
+
cogn init <name> -d "description"
|
|
250
|
+
cogn init <name> --format v22 # Create v2.2 format module
|
|
251
|
+
|
|
252
|
+
# Migrate modules
|
|
253
|
+
cogn migrate <module> # Migrate v1/v2.1 module to v2.2
|
|
254
|
+
|
|
255
|
+
# Install from GitHub (recommended)
|
|
256
|
+
cogn add ziel-io/cognitive-modules -m code-simplifier
|
|
257
|
+
cogn add org/repo -m module-name --tag v1.0.0 # Install specific version
|
|
258
|
+
cogn remove <module> # Remove module
|
|
259
|
+
|
|
260
|
+
# Version management
|
|
261
|
+
cogn update <module> # Update to latest version
|
|
262
|
+
cogn update <module> --tag v2.0.0 # Update to specific version
|
|
263
|
+
cogn versions <url> # View available versions
|
|
264
|
+
|
|
265
|
+
# Other installation methods
|
|
266
|
+
cogn install github:user/repo/path
|
|
267
|
+
cogn install registry:module-name
|
|
268
|
+
cogn uninstall <module>
|
|
269
|
+
|
|
270
|
+
# Registry
|
|
271
|
+
cogn registry # View public modules
|
|
272
|
+
cogn search <query> # Search modules
|
|
273
|
+
|
|
274
|
+
# Environment check
|
|
275
|
+
cogn doctor
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## Built-in Modules
|
|
279
|
+
|
|
280
|
+
| Module | Tier | Function | Example |
|
|
281
|
+
|--------|------|----------|---------|
|
|
282
|
+
| `code-reviewer` | decision | Code review | `cogn run code-reviewer --args "your code"` |
|
|
283
|
+
| `code-simplifier` | decision | Code simplification | `cogn run code-simplifier --args "complex code"` |
|
|
284
|
+
| `task-prioritizer` | decision | Task priority sorting | `cogn run task-prioritizer --args "task1,task2"` |
|
|
285
|
+
| `api-designer` | decision | REST API design | `cogn run api-designer --args "order system"` |
|
|
286
|
+
| `ui-spec-generator` | exploration | UI spec generation | `cogn run ui-spec-generator --args "e-commerce homepage"` |
|
|
287
|
+
| `product-analyzer` | exploration | Product analysis (subagent) | `cogn run product-analyzer --args "health product" -s` |
|
|
288
|
+
|
|
289
|
+
## Module Format
|
|
290
|
+
|
|
291
|
+
### v2.2 Format (Recommended)
|
|
292
|
+
|
|
293
|
+
```
|
|
294
|
+
my-module/
|
|
295
|
+
├── module.yaml # Machine-readable manifest (with tier/overflow/enums)
|
|
296
|
+
├── prompt.md # Human-readable prompt
|
|
297
|
+
├── schema.json # meta + input + data + error schemas
|
|
298
|
+
└── tests/ # Golden test cases
|
|
299
|
+
├── case1.input.json
|
|
300
|
+
└── case1.expected.json
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### module.yaml (v2.2)
|
|
304
|
+
|
|
305
|
+
```yaml
|
|
306
|
+
name: my-module
|
|
307
|
+
version: 2.2.0
|
|
308
|
+
responsibility: One-line description
|
|
309
|
+
|
|
310
|
+
tier: decision # exec | decision | exploration
|
|
311
|
+
schema_strictness: medium # high | medium | low
|
|
312
|
+
|
|
313
|
+
excludes:
|
|
314
|
+
- things not to do
|
|
315
|
+
|
|
316
|
+
policies:
|
|
317
|
+
network: deny
|
|
318
|
+
filesystem_write: deny
|
|
319
|
+
side_effects: deny
|
|
320
|
+
|
|
321
|
+
overflow:
|
|
322
|
+
enabled: true
|
|
323
|
+
recoverable: true
|
|
324
|
+
max_items: 5
|
|
325
|
+
require_suggested_mapping: true
|
|
326
|
+
|
|
327
|
+
enums:
|
|
328
|
+
strategy: extensible # strict | extensible
|
|
329
|
+
|
|
330
|
+
failure:
|
|
331
|
+
contract: error_union
|
|
332
|
+
partial_allowed: true
|
|
333
|
+
|
|
334
|
+
compat:
|
|
335
|
+
accepts_v21_payload: true
|
|
336
|
+
runtime_auto_wrap: true
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
### v1 Format (Still Supported)
|
|
340
|
+
|
|
341
|
+
```
|
|
342
|
+
my-module/
|
|
343
|
+
├── MODULE.md # Metadata + instructions
|
|
344
|
+
├── schema.json # Input/output schema
|
|
345
|
+
└── examples/
|
|
346
|
+
├── input.json
|
|
347
|
+
└── output.json
|
|
348
|
+
```
|
|
349
|
+
|
|
350
|
+
## Tier Explanation
|
|
351
|
+
|
|
352
|
+
| Tier | Purpose | Schema Strictness | Overflow |
|
|
353
|
+
|------|---------|-------------------|----------|
|
|
354
|
+
| `exec` | Auto-execution (patch, instruction generation) | high | Disabled |
|
|
355
|
+
| `decision` | Judgment/evaluation/classification | medium | Enabled |
|
|
356
|
+
| `exploration` | Exploration/research/inspiration | low | Enabled |
|
|
357
|
+
|
|
358
|
+
## v2.5 Streaming & Multimodal
|
|
359
|
+
|
|
360
|
+
### Streaming Response
|
|
361
|
+
|
|
362
|
+
Enable real-time streaming for better UX:
|
|
363
|
+
|
|
364
|
+
```yaml
|
|
365
|
+
# module.yaml
|
|
366
|
+
response:
|
|
367
|
+
mode: streaming # sync | streaming | both
|
|
368
|
+
chunk_type: delta # delta | snapshot
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
**JavaScript/TypeScript Usage:**
|
|
372
|
+
|
|
373
|
+
```typescript
|
|
374
|
+
import { runModuleStream } from 'cognitive-modules-cli';
|
|
375
|
+
|
|
376
|
+
// Stream execution
|
|
377
|
+
for await (const chunk of runModuleStream(module, provider, { input })) {
|
|
378
|
+
if ('delta' in chunk.chunk) {
|
|
379
|
+
process.stdout.write(chunk.chunk.delta);
|
|
380
|
+
} else if ('final' in chunk) {
|
|
381
|
+
console.log('\nComplete:', chunk.data);
|
|
382
|
+
}
|
|
383
|
+
}
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
**Python Usage:**
|
|
387
|
+
|
|
388
|
+
```python
|
|
389
|
+
from cognitive import StreamingRunner
|
|
390
|
+
|
|
391
|
+
runner = StreamingRunner()
|
|
392
|
+
async for chunk in runner.execute_stream("image-analyzer", input_data):
|
|
393
|
+
if chunk.get("chunk"):
|
|
394
|
+
print(chunk["chunk"]["delta"], end="")
|
|
395
|
+
elif chunk.get("final"):
|
|
396
|
+
print("\nComplete:", chunk["data"])
|
|
397
|
+
```
|
|
398
|
+
|
|
399
|
+
### Multimodal Input
|
|
400
|
+
|
|
401
|
+
Enable image/audio/video processing:
|
|
402
|
+
|
|
403
|
+
```yaml
|
|
404
|
+
# module.yaml
|
|
405
|
+
modalities:
|
|
406
|
+
input: [text, image, audio]
|
|
407
|
+
output: [text, image]
|
|
408
|
+
```
|
|
409
|
+
|
|
410
|
+
**JavaScript/TypeScript Usage:**
|
|
411
|
+
|
|
412
|
+
```typescript
|
|
413
|
+
const result = await runModule(module, provider, {
|
|
414
|
+
input: {
|
|
415
|
+
prompt: "Describe this image",
|
|
416
|
+
images: [
|
|
417
|
+
{ type: "url", url: "https://example.com/image.jpg" },
|
|
418
|
+
{ type: "base64", media_type: "image/png", data: "iVBORw0K..." }
|
|
419
|
+
]
|
|
420
|
+
}
|
|
421
|
+
});
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
**Python Usage:**
|
|
425
|
+
|
|
426
|
+
```python
|
|
427
|
+
result = await runner.execute("image-analyzer", {
|
|
428
|
+
"prompt": "Describe this image",
|
|
429
|
+
"images": [
|
|
430
|
+
{"type": "url", "url": "https://example.com/image.jpg"},
|
|
431
|
+
{"type": "file", "path": "./local-image.png"}
|
|
432
|
+
]
|
|
433
|
+
})
|
|
434
|
+
|
|
435
|
+
## Using with AI Tools
|
|
436
|
+
|
|
437
|
+
### Cursor / Codex CLI
|
|
438
|
+
|
|
439
|
+
Create `AGENTS.md` in your project root:
|
|
440
|
+
|
|
441
|
+
```markdown
|
|
442
|
+
## Code Review
|
|
443
|
+
|
|
444
|
+
When code review is needed:
|
|
445
|
+
1. Read `~/.cognitive/modules/code-reviewer/MODULE.md`
|
|
446
|
+
2. Output in schema.json format
|
|
447
|
+
3. Include meta.explain + data.rationale
|
|
448
|
+
```
|
|
449
|
+
|
|
450
|
+
### Direct Conversation
|
|
451
|
+
|
|
452
|
+
```
|
|
453
|
+
Read ~/.cognitive/modules/code-reviewer/MODULE.md,
|
|
454
|
+
review this code: def login(u,p): ...
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
## LLM Configuration
|
|
458
|
+
|
|
459
|
+
```bash
|
|
460
|
+
# OpenAI
|
|
461
|
+
export LLM_PROVIDER=openai
|
|
462
|
+
export OPENAI_API_KEY=sk-xxx
|
|
463
|
+
|
|
464
|
+
# Anthropic Claude
|
|
465
|
+
export LLM_PROVIDER=anthropic
|
|
466
|
+
export ANTHROPIC_API_KEY=sk-ant-xxx
|
|
467
|
+
|
|
468
|
+
# MiniMax
|
|
469
|
+
export LLM_PROVIDER=minimax
|
|
470
|
+
export MINIMAX_API_KEY=sk-xxx
|
|
471
|
+
|
|
472
|
+
# Ollama (local)
|
|
473
|
+
export LLM_PROVIDER=ollama
|
|
474
|
+
|
|
475
|
+
# Check configuration
|
|
476
|
+
cogn doctor
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
## Migrating to v2.2
|
|
480
|
+
|
|
481
|
+
Migrate from v1 or v2.1 modules to v2.2:
|
|
482
|
+
|
|
483
|
+
```bash
|
|
484
|
+
# Auto-migrate single module
|
|
485
|
+
cogn migrate code-reviewer
|
|
486
|
+
|
|
487
|
+
# Migrate all modules
|
|
488
|
+
cogn migrate --all
|
|
489
|
+
|
|
490
|
+
# Verify migration result
|
|
491
|
+
cogn validate code-reviewer --v22
|
|
492
|
+
```
|
|
493
|
+
|
|
494
|
+
Manual migration steps:
|
|
495
|
+
1. Create `module.yaml` (add tier/overflow/enums)
|
|
496
|
+
2. Update `schema.json` (add meta schema)
|
|
497
|
+
3. Create/update `prompt.md` (describe v2.2 envelope format)
|
|
498
|
+
4. Keep `MODULE.md` (backward compatibility)
|
|
499
|
+
|
|
500
|
+
## Development
|
|
501
|
+
|
|
502
|
+
```bash
|
|
503
|
+
# Clone
|
|
504
|
+
git clone https://github.com/ziel-io/cognitive-modules.git
|
|
505
|
+
cd cognitive-modules
|
|
506
|
+
|
|
507
|
+
# Install dev dependencies
|
|
508
|
+
pip install -e ".[dev]"
|
|
509
|
+
|
|
510
|
+
# Run tests
|
|
511
|
+
pytest tests/ -v
|
|
512
|
+
|
|
513
|
+
# Create new module (v2.2 format)
|
|
514
|
+
cogn init my-module -d "module description" --format v22
|
|
515
|
+
cogn validate my-module --v22
|
|
516
|
+
```
|
|
517
|
+
|
|
518
|
+
## Project Structure
|
|
519
|
+
|
|
520
|
+
```
|
|
521
|
+
cognitive-modules/
|
|
522
|
+
├── src/cognitive/ # Python CLI source
|
|
523
|
+
│ ├── cli.py # Command entry
|
|
524
|
+
│ ├── loader.py # Module loader (supports v0/v1/v2.2)
|
|
525
|
+
│ ├── runner.py # Module executor (v2.2 envelope)
|
|
526
|
+
│ ├── validator.py # Module validator (includes v2.2 validation)
|
|
527
|
+
│ ├── migrate.py # v2.2 migration tool
|
|
528
|
+
│ ├── subagent.py # Subagent orchestration
|
|
529
|
+
│ ├── registry.py # Module installation
|
|
530
|
+
│ ├── templates.py # Module templates
|
|
531
|
+
│ └── providers/ # LLM backends
|
|
532
|
+
├── packages/
|
|
533
|
+
│ └── cli-node/ # Node.js CLI (npm: cognitive-modules-cli)
|
|
534
|
+
│ ├── src/ # TypeScript source
|
|
535
|
+
│ └── package.json
|
|
536
|
+
├── cognitive/modules/ # Built-in modules (all v2.2)
|
|
537
|
+
├── coze-plugin/ # Coze integration plugin
|
|
538
|
+
├── tests/ # Unit tests
|
|
539
|
+
├── SPEC.md # v0.1 specification (historical)
|
|
540
|
+
├── SPEC-v2.2.md # v2.2 specification (latest)
|
|
541
|
+
├── INTEGRATION.md # Integration guide
|
|
542
|
+
└── cognitive-registry.json # Public registry
|
|
543
|
+
```
|
|
544
|
+
|
|
545
|
+
## Multi-Platform Support
|
|
546
|
+
|
|
547
|
+
| Platform | Package | Command | Installation |
|
|
548
|
+
|----------|---------|---------|--------------|
|
|
549
|
+
| Python | `cognitive-modules` | `cogn` | `pip install cognitive-modules` |
|
|
550
|
+
| Node.js | `cogn` or `cognitive-modules-cli` | `cog` | `npm install -g cogn` or `npx cogn` |
|
|
551
|
+
|
|
552
|
+
Both versions share the same module format and v2.2 specification.
|
|
553
|
+
|
|
554
|
+
## Documentation
|
|
555
|
+
|
|
556
|
+
### Specification
|
|
557
|
+
|
|
558
|
+
| Document | Description |
|
|
559
|
+
|----------|-------------|
|
|
560
|
+
| [SPEC-v2.5.md](SPEC-v2.5.md) | v2.5 full specification (Streaming, Multimodal) |
|
|
561
|
+
| [SPEC-v2.5_zh.md](SPEC-v2.5_zh.md) | v2.5 规范中文版 |
|
|
562
|
+
| [SPEC-v2.2.md](SPEC-v2.2.md) | v2.2 full specification (Control/Data separation, Tier, Overflow) |
|
|
563
|
+
| [SPEC-v2.2_zh.md](SPEC-v2.2_zh.md) | v2.2 规范中文版 |
|
|
564
|
+
| [SPEC.md](SPEC.md) | v0.1 specification (context philosophy) |
|
|
565
|
+
|
|
566
|
+
### For Implementers
|
|
567
|
+
|
|
568
|
+
| Document | Description |
|
|
569
|
+
|----------|-------------|
|
|
570
|
+
| [IMPLEMENTERS-GUIDE.md](IMPLEMENTERS-GUIDE.md) | Step-by-step guide for building a runtime |
|
|
571
|
+
| [CONFORMANCE.md](CONFORMANCE.md) | Conformance levels (Level 1/2/3) |
|
|
572
|
+
| [ERROR-CODES.md](ERROR-CODES.md) | Standard error code taxonomy (E1xxx-E4xxx) |
|
|
573
|
+
| [templates/runtime-starter/](templates/runtime-starter/) | Starter template for new implementations |
|
|
574
|
+
|
|
575
|
+
### Advanced Features
|
|
576
|
+
|
|
577
|
+
| Document | Description |
|
|
578
|
+
|----------|-------------|
|
|
579
|
+
| [COMPOSITION.md](COMPOSITION.md) | Module composition and dataflow specification |
|
|
580
|
+
| [CONTEXT-PROTOCOL.md](CONTEXT-PROTOCOL.md) | Context protocol for stateful workflows |
|
|
581
|
+
|
|
582
|
+
### Schemas & Test Vectors
|
|
583
|
+
|
|
584
|
+
| Resource | Description |
|
|
585
|
+
|----------|-------------|
|
|
586
|
+
| [spec/response-envelope.schema.json](spec/response-envelope.schema.json) | JSON Schema for v2.2 envelope validation |
|
|
587
|
+
| [spec/module.yaml.schema.json](spec/module.yaml.schema.json) | JSON Schema for module.yaml |
|
|
588
|
+
| [spec/test-vectors/](spec/test-vectors/) | Official test vectors for compliance |
|
|
589
|
+
|
|
590
|
+
### Registry & Distribution
|
|
591
|
+
|
|
592
|
+
| Resource | Description |
|
|
593
|
+
|----------|-------------|
|
|
594
|
+
| [REGISTRY-PROTOCOL.md](REGISTRY-PROTOCOL.md) | Registry protocol specification |
|
|
595
|
+
| [spec/registry-entry.schema.json](spec/registry-entry.schema.json) | Registry entry JSON Schema |
|
|
596
|
+
| [cognitive-registry.json](cognitive-registry.json) | Current public registry |
|
|
597
|
+
| [CERTIFICATION.md](CERTIFICATION.md) | Certification program (badges, verification) |
|
|
598
|
+
|
|
599
|
+
### Governance
|
|
600
|
+
|
|
601
|
+
| Document | Description |
|
|
602
|
+
|----------|-------------|
|
|
603
|
+
| [GOVERNANCE.md](GOVERNANCE.md) | Project governance structure |
|
|
604
|
+
| [CMEP-PROCESS.md](CMEP-PROCESS.md) | Enhancement proposal process |
|
|
605
|
+
|
|
606
|
+
### Integration
|
|
607
|
+
|
|
608
|
+
| Document | Description |
|
|
609
|
+
|----------|-------------|
|
|
610
|
+
| [INTEGRATION.md](INTEGRATION.md) | Agent tool integration guide |
|
|
611
|
+
| [COGNITIVE-PROTOCOL.md](COGNITIVE-PROTOCOL.md) | Protocol details |
|
|
612
|
+
|
|
613
|
+
## License
|
|
614
|
+
|
|
615
|
+
MIT
|
|
@@ -1,18 +1,18 @@
|
|
|
1
|
-
cognitive/__init__.py,sha256=
|
|
1
|
+
cognitive/__init__.py,sha256=FY2NWSVD9Lq_L9DrUPjkacIex_tD2P1xYrC9qawrMYM,401
|
|
2
2
|
cognitive/cli.py,sha256=tYYWkFJt-eBtWF3GwokuqIZz6vFIP3ZJj7yls1cru6E,26778
|
|
3
|
-
cognitive/loader.py,sha256=
|
|
3
|
+
cognitive/loader.py,sha256=NgFNcGXO56_1T1qxdvwWrpE37NoysTpuKhcQtchnros,15052
|
|
4
4
|
cognitive/mcp_server.py,sha256=NUQT7IqdYB9tQ-1YYfG5MPJuq6A70FXlcV2x3lBnuvM,6852
|
|
5
|
-
cognitive/migrate.py,sha256=
|
|
5
|
+
cognitive/migrate.py,sha256=FzdEwQvLWxmXy09fglV0YRxK4ozNeNT9UacfxGSJPZU,20156
|
|
6
6
|
cognitive/registry.py,sha256=qLGyvUxSDP4frs46UlPa5jCcKubqiikWT3Y9JrBqfFc,18549
|
|
7
|
-
cognitive/runner.py,sha256
|
|
7
|
+
cognitive/runner.py,sha256=-uUplBJvLpJJyw7YhD3Nzm-TOggSA2AbyDq5iRNLbXo,38853
|
|
8
8
|
cognitive/server.py,sha256=cz8zGqhGrZgFY-HM0RSCjPCpB_Mfg1jsybeoo2ALvAc,9041
|
|
9
9
|
cognitive/subagent.py,sha256=fb7LWwNF6YcJtC_T1dK0EvzqWMBnav-kiCIpvVohEBw,8142
|
|
10
10
|
cognitive/templates.py,sha256=lKC197X9aQIA-npUvVCaplSwvhxjsH_KYVCQtrTZrL4,4712
|
|
11
11
|
cognitive/validator.py,sha256=8B02JQQdNcwvH-mtbyP8bVTRQxUrO9Prt4gU0N53fdg,21843
|
|
12
12
|
cognitive/providers/__init__.py,sha256=hqhVA1IEXpVtyCAteXhO5yD8a8ikQpVIPEKJVHLtRFY,7492
|
|
13
|
-
cognitive_modules-0.
|
|
14
|
-
cognitive_modules-0.
|
|
15
|
-
cognitive_modules-0.
|
|
16
|
-
cognitive_modules-0.
|
|
17
|
-
cognitive_modules-0.
|
|
18
|
-
cognitive_modules-0.
|
|
13
|
+
cognitive_modules-0.6.0.dist-info/licenses/LICENSE,sha256=NXFYUy2hPJdh3NHRxMChTnMiQD9k8zFxkmR7gWefexc,1064
|
|
14
|
+
cognitive_modules-0.6.0.dist-info/METADATA,sha256=7tUzBzklyYkdZVgjL7WPu1yQqljiaO3RC9zSsQF5JEY,18880
|
|
15
|
+
cognitive_modules-0.6.0.dist-info/WHEEL,sha256=wUyA8OaulRlbfwMtmQsvNngGrxQHAvkKcvRmdizlJi0,92
|
|
16
|
+
cognitive_modules-0.6.0.dist-info/entry_points.txt,sha256=1yqKB-MjHrRoe8FcYm-TgZDqGEZxzBPsd0xC4pcfBNU,43
|
|
17
|
+
cognitive_modules-0.6.0.dist-info/top_level.txt,sha256=kGIfDucCKylo8cRBtxER_v3DHIea-Sol9x9YSJo1u3Y,10
|
|
18
|
+
cognitive_modules-0.6.0.dist-info/RECORD,,
|