xcomponent-ai 0.1.1

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 (49) hide show
  1. package/CONTRIBUTING.md +195 -0
  2. package/LICENSE +45 -0
  3. package/PERSISTENCE.md +774 -0
  4. package/README.md +594 -0
  5. package/dist/agents.d.ts +81 -0
  6. package/dist/agents.d.ts.map +1 -0
  7. package/dist/agents.js +405 -0
  8. package/dist/agents.js.map +1 -0
  9. package/dist/api.d.ts +36 -0
  10. package/dist/api.d.ts.map +1 -0
  11. package/dist/api.js +404 -0
  12. package/dist/api.js.map +1 -0
  13. package/dist/cli.d.ts +7 -0
  14. package/dist/cli.d.ts.map +1 -0
  15. package/dist/cli.js +437 -0
  16. package/dist/cli.js.map +1 -0
  17. package/dist/component-registry.d.ts +190 -0
  18. package/dist/component-registry.d.ts.map +1 -0
  19. package/dist/component-registry.js +382 -0
  20. package/dist/component-registry.js.map +1 -0
  21. package/dist/fsm-runtime.d.ts +263 -0
  22. package/dist/fsm-runtime.d.ts.map +1 -0
  23. package/dist/fsm-runtime.js +1122 -0
  24. package/dist/fsm-runtime.js.map +1 -0
  25. package/dist/index.d.ts +23 -0
  26. package/dist/index.d.ts.map +1 -0
  27. package/dist/index.js +56 -0
  28. package/dist/index.js.map +1 -0
  29. package/dist/monitoring.d.ts +68 -0
  30. package/dist/monitoring.d.ts.map +1 -0
  31. package/dist/monitoring.js +176 -0
  32. package/dist/monitoring.js.map +1 -0
  33. package/dist/persistence.d.ts +100 -0
  34. package/dist/persistence.d.ts.map +1 -0
  35. package/dist/persistence.js +270 -0
  36. package/dist/persistence.js.map +1 -0
  37. package/dist/timer-wheel.d.ts +85 -0
  38. package/dist/timer-wheel.d.ts.map +1 -0
  39. package/dist/timer-wheel.js +181 -0
  40. package/dist/timer-wheel.js.map +1 -0
  41. package/dist/types.d.ts +404 -0
  42. package/dist/types.d.ts.map +1 -0
  43. package/dist/types.js +40 -0
  44. package/dist/types.js.map +1 -0
  45. package/dist/websockets.d.ts +32 -0
  46. package/dist/websockets.d.ts.map +1 -0
  47. package/dist/websockets.js +117 -0
  48. package/dist/websockets.js.map +1 -0
  49. package/package.json +103 -0
package/CONTRIBUTING.md ADDED
@@ -0,0 +1,195 @@
1
+ # Contributing to xcomponent-ai
2
+
3
+ Thank you for your interest in contributing to xcomponent-ai! This document provides guidelines and instructions for contributing.
4
+
5
+ ## Code of Conduct
6
+
7
+ By participating in this project, you agree to maintain a respectful and inclusive environment for all contributors.
8
+
9
+ ## How to Contribute
10
+
11
+ ### Reporting Bugs
12
+
13
+ 1. Check if the bug has already been reported in [Issues](https://github.com/fredericcarre/mayele-ai/issues)
14
+ 2. If not, create a new issue with:
15
+ - Clear, descriptive title
16
+ - Steps to reproduce
17
+ - Expected vs actual behavior
18
+ - Environment details (Node version, OS, etc.)
19
+ - Code samples if applicable
20
+
21
+ ### Suggesting Features
22
+
23
+ 1. Check existing [Discussions](https://github.com/fredericcarre/mayele-ai/discussions) and Issues
24
+ 2. Create a new discussion with:
25
+ - Use case description
26
+ - Proposed solution
27
+ - Alternatives considered
28
+ - Example code/FSM definitions
29
+
30
+ ### Pull Requests
31
+
32
+ 1. **Fork and Clone**
33
+ ```bash
34
+ git clone https://github.com/YOUR_USERNAME/mayele-ai.git
35
+ cd mayele-ai
36
+ npm install
37
+ ```
38
+
39
+ 2. **Create a Feature Branch**
40
+ ```bash
41
+ git checkout -b feature/my-feature
42
+ ```
43
+
44
+ 3. **Make Changes**
45
+ - Follow TypeScript strict mode
46
+ - Write tests (maintain >80% coverage)
47
+ - Add JSDoc comments to public APIs
48
+ - Update README if needed
49
+
50
+ 4. **Run Tests**
51
+ ```bash
52
+ npm test
53
+ npm run build
54
+ ```
55
+
56
+ 5. **Commit**
57
+ ```bash
58
+ git commit -m "feat: add my feature"
59
+ ```
60
+
61
+ Use conventional commits:
62
+ - `feat:` New feature
63
+ - `fix:` Bug fix
64
+ - `docs:` Documentation
65
+ - `test:` Tests
66
+ - `refactor:` Code refactoring
67
+ - `chore:` Maintenance
68
+
69
+ 6. **Push and Create PR**
70
+ ```bash
71
+ git push origin feature/my-feature
72
+ ```
73
+
74
+ Then create a Pull Request on GitHub with:
75
+ - Clear description of changes
76
+ - Link to related issues
77
+ - Screenshots/examples if applicable
78
+
79
+ ## Development Guidelines
80
+
81
+ ### Code Style
82
+
83
+ - Use TypeScript strict mode
84
+ - Follow existing code patterns
85
+ - Use meaningful variable names
86
+ - Keep functions small and focused
87
+ - Add JSDoc comments to public APIs
88
+
89
+ ### Testing
90
+
91
+ - Write unit tests for new features
92
+ - Maintain >80% code coverage
93
+ - Test edge cases and error scenarios
94
+ - Use descriptive test names
95
+
96
+ Example:
97
+ ```typescript
98
+ describe('FSMRuntime', () => {
99
+ describe('Instance Management', () => {
100
+ it('should create an instance with initial context', () => {
101
+ // Test implementation
102
+ });
103
+ });
104
+ });
105
+ ```
106
+
107
+ ### Documentation
108
+
109
+ - Update README for new features
110
+ - Add JSDoc comments with examples
111
+ - Create/update Mermaid diagrams if architecture changes
112
+ - Include example FSM definitions for new use cases
113
+
114
+ ### Commit Messages
115
+
116
+ Follow conventional commits:
117
+ ```
118
+ <type>(<scope>): <subject>
119
+
120
+ <body>
121
+
122
+ <footer>
123
+ ```
124
+
125
+ Example:
126
+ ```
127
+ feat(agents): add compliance gap detection for GDPR
128
+
129
+ Implemented automatic detection of missing GDPR compliance guards
130
+ in FSM definitions. The FSMAgent now suggests adding consent checks
131
+ and data retention policies when user-related workflows are detected.
132
+
133
+ Closes #42
134
+ ```
135
+
136
+ ## Project Structure
137
+
138
+ ```
139
+ xcomponent-ai/
140
+ ├── src/
141
+ │ ├── types.ts # Type definitions
142
+ │ ├── fsm-runtime.ts # Core FSM runtime
143
+ │ ├── agents.ts # Agentic AI layer
144
+ │ ├── monitoring.ts # Monitoring service
145
+ │ ├── websockets.ts # WebSocket infrastructure
146
+ │ ├── api.ts # Express API server
147
+ │ ├── cli.ts # CLI commands
148
+ │ └── index.ts # Public exports
149
+ ├── tests/ # Jest tests
150
+ ├── examples/ # Example FSM definitions
151
+ ├── docs/ # Generated documentation
152
+ └── .github/workflows/ # CI/CD
153
+ ```
154
+
155
+ ## Testing Your Changes
156
+
157
+ ```bash
158
+ # Run all tests
159
+ npm test
160
+
161
+ # Run tests in watch mode
162
+ npm run test:watch
163
+
164
+ # Run tests with coverage
165
+ npm test -- --coverage
166
+
167
+ # Build project
168
+ npm run build
169
+
170
+ # Generate documentation
171
+ npm run doc
172
+
173
+ # Test CLI locally
174
+ npm run cli -- load examples/trading.yaml
175
+ ```
176
+
177
+ ## Release Process
178
+
179
+ (For maintainers only)
180
+
181
+ 1. Update version in `package.json`
182
+ 2. Update CHANGELOG.md
183
+ 3. Create git tag: `git tag v0.x.0`
184
+ 4. Push: `git push --tags`
185
+ 5. Publish to npm: `npm publish`
186
+
187
+ ## Questions?
188
+
189
+ - Open a [Discussion](https://github.com/fredericcarre/mayele-ai/discussions)
190
+ - Join our community chat (coming soon)
191
+ - Email: contributors@xcomponent.com
192
+
193
+ ## License
194
+
195
+ By contributing, you agree that your contributions will be licensed under the Apache License 2.0.
package/LICENSE ADDED
@@ -0,0 +1,45 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
10
+
11
+ "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
12
+
13
+ "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity.
14
+
15
+ "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
16
+
17
+ "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
18
+
19
+ "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
20
+
21
+ "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License.
22
+
23
+ "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work.
24
+
25
+ "Contribution" shall mean any work of authorship that is intentionally submitted to the Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner.
26
+
27
+ "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor.
28
+
29
+ 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
30
+
31
+ 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work.
32
+
33
+ Copyright 2026 XComponent AI Contributors
34
+
35
+ Licensed under the Apache License, Version 2.0 (the "License");
36
+ you may not use this file except in compliance with the License.
37
+ You may obtain a copy of the License at
38
+
39
+ http://www.apache.org/licenses/LICENSE-2.0
40
+
41
+ Unless required by applicable law or agreed to in writing, software
42
+ distributed under the License is distributed on an "AS IS" BASIS,
43
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
44
+ See the License for the specific language governing permissions and
45
+ limitations under the License.