@cagent/chat-embedding-core 0.0.2 → 0.0.5

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 (4) hide show
  1. package/AGENTS.md +184 -184
  2. package/dist/web.js +1 -1
  3. package/docs/embedding-style-guide.md +417 -0
  4. package/package.json +4 -3
package/AGENTS.md CHANGED
@@ -1,184 +1,184 @@
1
- # AGENTS.md - Coding Guidelines
2
-
3
- > **Purpose:** Guidelines for code quality, development process, and decision-making
4
- > **Target Audience:** AI coding assistants and developers
5
- > **Version:** 1.0
6
-
7
- ---
8
-
9
- ## Code Quality Standards
10
-
11
- ### Core Principles
12
-
13
- #### No Unused Code
14
-
15
- - **Rule:** Don't write unused code
16
- - **Requirement:** Ensure everything written is utilized in the project
17
- - **Priority:** Critical
18
-
19
- #### Readability First
20
-
21
- - **Rule:** Prioritize readability for human understanding over execution efficiency
22
- - **Priority:** Critical
23
-
24
- #### Maintainability
25
-
26
- - **Rule:** Maintain long-term maintainability over short-term optimization
27
- - **Priority:** High
28
-
29
- #### Simplicity
30
-
31
- - **Rule:** Avoid unnecessary complexity
32
- - **Approach:** Implement simple solutions unless complexity is truly required
33
- - **Priority:** High
34
-
35
- #### Clean Code Philosophy
36
-
37
- - **Rule:** Follow Linus Torvalds' clean code principles
38
- - **Priority:** High
39
- - **Guidelines:**
40
- 1. Keep it simple
41
- 2. Make code readable like prose
42
- 3. Avoid premature optimization
43
- 4. Express intent clearly
44
- 5. Minimize abstraction layers
45
-
46
- ---
47
-
48
- ### Documentation Standards
49
-
50
- #### Comment Purpose
51
-
52
- - **Rule:** Comments must explain "what" (business logic/purpose) and "why" (reasoning/decisions), not "how"
53
- - **Priority:** High
54
-
55
- #### Avoid Over-Commenting
56
-
57
- - **Rule:** Avoid over-commenting
58
- - **Rationale:** Excessive comments indicate poor code quality
59
- - **Priority:** Medium
60
-
61
- #### Function Comments
62
-
63
- - **Rule:** Function comments must explain purpose and reasoning
64
- - **Placement:** Placed at function beginnings
65
- - **Priority:** Medium
66
-
67
- #### Self-Explanatory Code
68
-
69
- - **Rule:** Well-written code should be self-explanatory
70
- - **Method:** Through meaningful names and clear structure
71
- - **Priority:** High
72
-
73
- ---
74
-
75
- ## Development Process
76
-
77
- > **Description:** Follow these steps in order for effective development
78
- > **Priority:** Critical
79
-
80
- | Step | Name | Action/Rationale | Importance |
81
- | ---- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
82
- | 1 | Understand First | Use available tools to understand data structures before implementation | Critical |
83
- | 2 | Design Data Structures | Good data structures lead to good code | Critical |
84
- | 3 | Define Interfaces | Specify all input/output structures before writing logic | High |
85
- | 4 | Define Functions | Create all function signatures before implementation | High |
86
- | 5 | Implement Logic | Write implementation only after structures and definitions are complete | High |
87
- | 6 | Validate Code Quality | Always run lint and typecheck after writing code. Fix all linting errors and type errors before considering the task complete. Zero tolerance for lint and typecheck errors | Critical |
88
-
89
- ---
90
-
91
- ## Quality Guidelines
92
-
93
- #### Avoid Over-Engineering
94
-
95
- - **Rule:** Avoid over-engineering
96
- - **Focus:** Focus on minimal viable solutions meeting acceptance criteria
97
- - **Priority:** High
98
-
99
- #### Testing Approach
100
-
101
- - **Rule:** Only create automated tests if explicitly required
102
- - **Priority:** Medium
103
-
104
- #### Feature Scope
105
-
106
- - **Rule:** Never add functionality "just in case"
107
- - **Requirement:** Implement only what's needed now
108
- - **Priority:** High
109
-
110
- #### Code Validation
111
-
112
- - **Rule:** Always run lint and typecheck after code changes
113
- - **Requirement:** Must fix all linting and type checking errors before completion
114
- - **Process:** Run lint command, then typecheck command. Address all errors and warnings
115
- - **Tolerance:** Zero tolerance for lint or typecheck errors
116
- - **Priority:** Critical
117
-
118
- ---
119
-
120
- ## Decision Making Framework
121
-
122
- > **Description:** Apply these principles systematically for all decisions
123
- > **Priority:** High
124
-
125
- | Step | Principle | Importance |
126
- | ---- | ---------------------------- | ---------- |
127
- | 1 | Gather Complete Information | Critical |
128
- | 2 | Multi-Perspective Analysis | High |
129
- | 3 | Consider All Stakeholders | High |
130
- | 4 | Evaluate Alternatives | High |
131
- | 5 | Assess Impact & Consequences | High |
132
- | 6 | Apply Ethical Framework | Medium |
133
- | 7 | Take Responsibility | High |
134
- | 8 | Learn & Adapt | High |
135
-
136
- ---
137
-
138
- ## Code Validation Workflow
139
-
140
- > **Description:** Mandatory validation process after writing or modifying code
141
- > **Priority:** Critical
142
-
143
- #### Validation Commands
144
-
145
- - **Lint Fix Command:** `bun run lint-fix`
146
- - **Type Check Command:** `bun run type-check`
147
- - **Combined Command:** `bun run lint-fix && bun run type-check`
148
-
149
- #### Required Workflow
150
-
151
- | Step | Action | Description |
152
- | ---- | --------------- | -------------------------------------------------- |
153
- | 1 | Write/Edit Code | Make your code changes |
154
- | 2 | Run Validation | Execute `bun run lint-fix && bun run type-check` |
155
- | 3 | Review Results | Check for any remaining errors |
156
- | 4 | Fix Errors | Address all lint and type errors |
157
- | 5 | Repeat | Run validation again until all errors are resolved |
158
-
159
- #### Rules
160
-
161
- - **Rule:** Always run validation commands after every code change
162
- - **Requirement:** Must run both lint-fix and type-check before considering task complete
163
- - **Tolerance:** Zero errors allowed - all lint and type errors must be fixed
164
- - **Priority:** Critical
165
-
166
- ---
167
-
168
- ## Package Manager
169
-
170
- #### Required Package Manager
171
-
172
- - **Rule:** Use `bun` as the package manager for this project
173
- - **Requirement:** All package installations and script executions must use `bun`
174
- - **Prohibited:** Do NOT use `npm`, `pnpm`, or `yarn`
175
- - **Priority:** Critical
176
-
177
- #### Examples
178
-
179
- | Action | Correct | Incorrect |
180
- | -------------------- | ---------------------- | ----------------------------- |
181
- | Install dependencies | `bun install` | `npm install`, `yarn install` |
182
- | Add package | `bun add <package>` | `npm install <package>` |
183
- | Run script | `bun run <script>` | `npm run <script>` |
184
- | Remove package | `bun remove <package>` | `npm uninstall <package>` |
1
+ # AGENTS.md - Coding Guidelines
2
+
3
+ > **Purpose:** Guidelines for code quality, development process, and decision-making
4
+ > **Target Audience:** AI coding assistants and developers
5
+ > **Version:** 1.0
6
+
7
+ ---
8
+
9
+ ## Code Quality Standards
10
+
11
+ ### Core Principles
12
+
13
+ #### No Unused Code
14
+
15
+ - **Rule:** Don't write unused code
16
+ - **Requirement:** Ensure everything written is utilized in the project
17
+ - **Priority:** Critical
18
+
19
+ #### Readability First
20
+
21
+ - **Rule:** Prioritize readability for human understanding over execution efficiency
22
+ - **Priority:** Critical
23
+
24
+ #### Maintainability
25
+
26
+ - **Rule:** Maintain long-term maintainability over short-term optimization
27
+ - **Priority:** High
28
+
29
+ #### Simplicity
30
+
31
+ - **Rule:** Avoid unnecessary complexity
32
+ - **Approach:** Implement simple solutions unless complexity is truly required
33
+ - **Priority:** High
34
+
35
+ #### Clean Code Philosophy
36
+
37
+ - **Rule:** Follow Linus Torvalds' clean code principles
38
+ - **Priority:** High
39
+ - **Guidelines:**
40
+ 1. Keep it simple
41
+ 2. Make code readable like prose
42
+ 3. Avoid premature optimization
43
+ 4. Express intent clearly
44
+ 5. Minimize abstraction layers
45
+
46
+ ---
47
+
48
+ ### Documentation Standards
49
+
50
+ #### Comment Purpose
51
+
52
+ - **Rule:** Comments must explain "what" (business logic/purpose) and "why" (reasoning/decisions), not "how"
53
+ - **Priority:** High
54
+
55
+ #### Avoid Over-Commenting
56
+
57
+ - **Rule:** Avoid over-commenting
58
+ - **Rationale:** Excessive comments indicate poor code quality
59
+ - **Priority:** Medium
60
+
61
+ #### Function Comments
62
+
63
+ - **Rule:** Function comments must explain purpose and reasoning
64
+ - **Placement:** Placed at function beginnings
65
+ - **Priority:** Medium
66
+
67
+ #### Self-Explanatory Code
68
+
69
+ - **Rule:** Well-written code should be self-explanatory
70
+ - **Method:** Through meaningful names and clear structure
71
+ - **Priority:** High
72
+
73
+ ---
74
+
75
+ ## Development Process
76
+
77
+ > **Description:** Follow these steps in order for effective development
78
+ > **Priority:** Critical
79
+
80
+ | Step | Name | Action/Rationale | Importance |
81
+ | ---- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
82
+ | 1 | Understand First | Use available tools to understand data structures before implementation | Critical |
83
+ | 2 | Design Data Structures | Good data structures lead to good code | Critical |
84
+ | 3 | Define Interfaces | Specify all input/output structures before writing logic | High |
85
+ | 4 | Define Functions | Create all function signatures before implementation | High |
86
+ | 5 | Implement Logic | Write implementation only after structures and definitions are complete | High |
87
+ | 6 | Validate Code Quality | Always run lint and typecheck after writing code. Fix all linting errors and type errors before considering the task complete. Zero tolerance for lint and typecheck errors | Critical |
88
+
89
+ ---
90
+
91
+ ## Quality Guidelines
92
+
93
+ #### Avoid Over-Engineering
94
+
95
+ - **Rule:** Avoid over-engineering
96
+ - **Focus:** Focus on minimal viable solutions meeting acceptance criteria
97
+ - **Priority:** High
98
+
99
+ #### Testing Approach
100
+
101
+ - **Rule:** Only create automated tests if explicitly required
102
+ - **Priority:** Medium
103
+
104
+ #### Feature Scope
105
+
106
+ - **Rule:** Never add functionality "just in case"
107
+ - **Requirement:** Implement only what's needed now
108
+ - **Priority:** High
109
+
110
+ #### Code Validation
111
+
112
+ - **Rule:** Always run lint and typecheck after code changes
113
+ - **Requirement:** Must fix all linting and type checking errors before completion
114
+ - **Process:** Run lint command, then typecheck command. Address all errors and warnings
115
+ - **Tolerance:** Zero tolerance for lint or typecheck errors
116
+ - **Priority:** Critical
117
+
118
+ ---
119
+
120
+ ## Decision Making Framework
121
+
122
+ > **Description:** Apply these principles systematically for all decisions
123
+ > **Priority:** High
124
+
125
+ | Step | Principle | Importance |
126
+ | ---- | ---------------------------- | ---------- |
127
+ | 1 | Gather Complete Information | Critical |
128
+ | 2 | Multi-Perspective Analysis | High |
129
+ | 3 | Consider All Stakeholders | High |
130
+ | 4 | Evaluate Alternatives | High |
131
+ | 5 | Assess Impact & Consequences | High |
132
+ | 6 | Apply Ethical Framework | Medium |
133
+ | 7 | Take Responsibility | High |
134
+ | 8 | Learn & Adapt | High |
135
+
136
+ ---
137
+
138
+ ## Code Validation Workflow
139
+
140
+ > **Description:** Mandatory validation process after writing or modifying code
141
+ > **Priority:** Critical
142
+
143
+ #### Validation Commands
144
+
145
+ - **Lint Fix Command:** `bun run lint-fix`
146
+ - **Type Check Command:** `bun run type-check`
147
+ - **Combined Command:** `bun run lint-fix && bun run type-check`
148
+
149
+ #### Required Workflow
150
+
151
+ | Step | Action | Description |
152
+ | ---- | --------------- | -------------------------------------------------- |
153
+ | 1 | Write/Edit Code | Make your code changes |
154
+ | 2 | Run Validation | Execute `bun run lint-fix && bun run type-check` |
155
+ | 3 | Review Results | Check for any remaining errors |
156
+ | 4 | Fix Errors | Address all lint and type errors |
157
+ | 5 | Repeat | Run validation again until all errors are resolved |
158
+
159
+ #### Rules
160
+
161
+ - **Rule:** Always run validation commands after every code change
162
+ - **Requirement:** Must run both lint-fix and type-check before considering task complete
163
+ - **Tolerance:** Zero errors allowed - all lint and type errors must be fixed
164
+ - **Priority:** Critical
165
+
166
+ ---
167
+
168
+ ## Package Manager
169
+
170
+ #### Required Package Manager
171
+
172
+ - **Rule:** Use `bun` as the package manager for this project
173
+ - **Requirement:** All package installations and script executions must use `bun`
174
+ - **Prohibited:** Do NOT use `npm`, `pnpm`, or `yarn`
175
+ - **Priority:** Critical
176
+
177
+ #### Examples
178
+
179
+ | Action | Correct | Incorrect |
180
+ | -------------------- | ---------------------- | ----------------------------- |
181
+ | Install dependencies | `bun install` | `npm install`, `yarn install` |
182
+ | Add package | `bun add <package>` | `npm install <package>` |
183
+ | Run script | `bun run <script>` | `npm run <script>` |
184
+ | Remove package | `bun remove <package>` | `npm uninstall <package>` |