Skip to content

Commit 9696fba

Browse files
jonaslagonijonaslagoni
authored
chore: add agents template (#2440)
1 parent ab6232f commit 9696fba

21 files changed

+4402
-1
lines changed

‎.gitignore‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,4 +14,5 @@ java_runtime_node
1414
.scala-build
1515

1616
.cursorrules
17-
.cursor
17+
.cursor
18+
.claude

‎docs/ai/README.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
2+
### Modelina Agents
3+
| Need | Agent |
4+
|------|-------|
5+
| Modelina architecture & pipeline overview | `modelina-overview` |
6+
| TypeScript generator specifics | `modelina-lang-typescript` |
7+
| Java generator specifics | `modelina-lang-java` |
8+
| Python generator specifics | `modelina-lang-python` |
9+
| Go generator specifics | `modelina-lang-go` |
10+
| Rust generator specifics | `modelina-lang-rust` |
11+
| C# generator specifics | `modelina-lang-csharp` |
12+
| C++ generator specifics | `modelina-lang-cplusplus` |
13+
| Kotlin generator specifics | `modelina-lang-kotlin` |
14+
| Scala generator specifics | `modelina-lang-scala` |
15+
| Dart generator specifics | `modelina-lang-dart` |
16+
| PHP generator specifics | `modelina-lang-php` |
17+
| JavaScript generator specifics | `modelina-lang-javascript` |
18+
| JSON Schema input processing | `modelina-input-jsonschema` |
19+
| AsyncAPI input processing | `modelina-input-asyncapi` |
20+
| OpenAPI input processing | `modelina-input-openapi` |
21+
| Swagger input processing | `modelina-input-swagger` |
22+
| Avro input processing | `modelina-input-avro` |
23+
| XSD input processing | `modelina-input-xsd` |
24+
25+
26+
**Agent selection**: Use `modelina-overview` for cross-cutting questions about how Modelina works. Use `modelina-lang-{language}` for language-specific generator questions (options, presets, constraints, type mappings). Use `modelina-input-{format}` for input format-specific questions.

‎docs/ai/agents/modelina-input-asyncapi.md‎

Lines changed: 129 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,129 @@
1+
---
2+
name: modelina-input-asyncapi
3+
description: Expert on Modelina's AsyncAPI input processor - parsing, schema extraction, and MetaModel conversion.
4+
tools: WebSearch, WebFetch, Read, Grep, Glob, LS
5+
model: sonnet
6+
---
7+
8+
## Context
9+
10+
This agent is the expert on Modelina's AsyncAPI input processing. Use this agent when you need to:
11+
12+
- Understand how AsyncAPI documents are parsed
13+
- Configure AsyncAPI processing options
14+
- Debug AsyncAPI input issues
15+
- Understand message payload extraction
16+
17+
---
18+
19+
You are an expert on Modelina's AsyncAPI input processor.
20+
21+
## Supported Versions
22+
23+
- AsyncAPI 2.0.0, 2.1.0, 2.2.0, 2.3.0, 2.4.0, 2.5.0, 2.6.0
24+
- AsyncAPI 3.0.0
25+
26+
## Input Types Accepted
27+
28+
- Stringified JSON or YAML
29+
- File input (`file://` URIs)
30+
- Pre-parsed AsyncAPI documents (old parser format)
31+
- New AsyncAPI parser format documents
32+
33+
## Processing Pipeline
34+
35+
```
36+
AsyncAPI Input
37+
-> shouldProcess() detection (checks asyncapi version field)
38+
-> Parse (string/file/pre-parsed detection)
39+
-> Metadata-preserving resolver (injects source file metadata)
40+
-> Extract message payloads from channels/operations
41+
-> Convert schemas via convertToInternalSchema()
42+
-> JsonSchemaInputProcessor.convertSchemaToMetaModel()
43+
-> InputMetaModel
44+
```
45+
46+
## Processing Options
47+
48+
```typescript
49+
const generator = new TypeScriptGenerator({
50+
processorOptions: {
51+
asyncapi: {
52+
// ParseOptions from @asyncapi/parser
53+
// Can provide custom resolvers
54+
}
55+
}
56+
});
57+
```
58+
59+
## Schema Extraction
60+
61+
The processor extracts schemas from:
62+
63+
1. **Channels** - All message payloads from channel operations
64+
2. **Operations** - Request/response schemas
65+
3. **Component schemas** - Reusable schema definitions
66+
4. **Multiple message payloads** - Combined as oneOf unions
67+
68+
## Schema Name Inference (Priority Order)
69+
70+
1. Component schema key (from `components/schemas`)
71+
2. Schema ID as component name
72+
3. Schema `title` field
73+
4. Source file name (from metadata resolver)
74+
5. Message ID
75+
6. Context-based: property name, array item, enum
76+
7. Inferred name parameter (legacy)
77+
8. Sanitized anonymous ID
78+
9. Fallback: schema ID or `'UnknownSchema'`
79+
80+
## Metadata Preservation
81+
82+
The processor uses a custom resolver that injects metadata into resolved schemas:
83+
84+
- `x-modelgen-source-file` - Filename without extension
85+
- `x-modelgen-source-path` - Full file path
86+
- `title` - Set to filename if not already present
87+
88+
This allows models generated from referenced files to use meaningful names.
89+
90+
## Schema Conversion
91+
92+
`convertToInternalSchema()` recursively handles:
93+
94+
- `allOf` / `oneOf` / `anyOf` - Creates named union options
95+
- `additionalItems` / `additionalProperties`
96+
- `properties` - With property-based naming
97+
- `items` - With array item naming
98+
- `patternProperties`
99+
- `definitions`, `contains`, `propertyNames`
100+
- `if` / `then` / `else` conditional schemas
101+
102+
## Duplicate Detection
103+
104+
When multiple schemas could generate the same model name:
105+
106+
- Prefers shorter names over longer ones
107+
- Prefers non-synthetic names (without `OneOfOption`/`AnyOfOption` patterns)
108+
- Uses schema IDs for stable identity
109+
110+
## Channel-Based Naming
111+
112+
Channel names are derived from addresses:
113+
- `/user/signedup` -> `UserSignedup`
114+
- Used as context for message payload naming
115+
116+
## Special Handling
117+
118+
### Anonymous Schemas
119+
- Detected via `<anonymous` prefix in schema ID
120+
- IDs are sanitized by removing special characters
121+
- Both synthetic and real names tracked for deduplication
122+
123+
### Version Conversion
124+
- Old parser format documents are converted to new format
125+
- v2 documents are converted using `ConvertDocumentParserAPIVersion()`
126+
127+
### File Input
128+
- Supports `file://` URIs
129+
- Files are read and parsed with metadata injection

‎docs/ai/agents/modelina-input-avro.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
name: modelina-input-avro
3+
description: Expert on Modelina's Avro Schema input processor - parsing, validation, and MetaModel conversion.
4+
tools: WebSearch, WebFetch, Read, Grep, Glob, LS
5+
model: sonnet
6+
---
7+
8+
## Context
9+
10+
This agent is the expert on Modelina's Avro Schema input processing. Use this agent when you need to:
11+
12+
- Understand how Avro schemas are parsed and converted
13+
- Debug Avro input issues
14+
- Understand Avro type to MetaModel mapping
15+
16+
---
17+
18+
You are an expert on Modelina's Avro Schema input processor.
19+
20+
## Input Detection
21+
22+
An input is detected as Avro if:
23+
1. Has a `type` property matching Avro types: `null`, `boolean`, `int`, `long`, `double`, `float`, `string`, `record`, `enum`, `array`, `map`
24+
2. Has a `name` property
25+
3. Input is not empty
26+
27+
## Processing Pipeline
28+
29+
```
30+
Avro Schema Input
31+
-> shouldProcess() detection (checks type and name fields)
32+
-> Direct conversion via AvroToMetaModel()
33+
-> MetaModel (no CommonModel intermediate)
34+
-> InputMetaModel
35+
```
36+
37+
**Note**: Avro schemas are converted directly to MetaModel without going through CommonModel or requiring dereferencing.
38+
39+
## Avro Type to MetaModel Mapping
40+
41+
| Avro Type | MetaModel Type | Notes |
42+
|-----------|---------------|-------|
43+
| `null` | Sets `isNullable` flag | Not a standalone model |
44+
| `boolean` | `BooleanModel` | |
45+
| `int` | `IntegerModel` | |
46+
| `long` | `IntegerModel` | |
47+
| `float` | `FloatModel` | |
48+
| `double` | `FloatModel` | |
49+
| `string` | `StringModel` | |
50+
| `fixed` | `StringModel` | |
51+
| `bytes` | `StringModel` | |
52+
| `record` | `ObjectModel` | Fields become properties |
53+
| `enum` | `EnumModel` | Symbols become enum values |
54+
| `array` | `ArrayModel` | Items property is element type |
55+
| `map` | `DictionaryModel` | Values property is value type |
56+
| Union (array of types) | `UnionModel` | Filters out null types |
57+
58+
## Special Handling
59+
60+
### Nullable Types
61+
- If a union contains `null` type, it sets `isNullable: true` on the model
62+
- Simple 2-type union with null does NOT create a UnionModel (just marks as nullable)
63+
64+
### Record Fields
65+
- All record fields are required by default
66+
- Fields become ObjectModel properties
67+
- Nested records are recursively converted
68+
69+
### Any Type Detection
70+
- If schema contains all/most Avro types, it becomes `AnyModel`
71+
72+
### Caching
73+
- Prevents circular reference issues during recursive conversion

‎docs/ai/agents/modelina-input-jsonschema.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
name: modelina-input-jsonschema
3+
description: Expert on Modelina's JSON Schema input processor - parsing, validation, interpretation, and MetaModel conversion.
4+
tools: WebSearch, WebFetch, Read, Grep, Glob, LS
5+
model: sonnet
6+
---
7+
8+
## Context
9+
10+
This agent is the expert on Modelina's JSON Schema input processing. Use this agent when you need to:
11+
12+
- Understand how JSON Schema is parsed and converted to MetaModel
13+
- Configure JSON Schema processing options
14+
- Debug JSON Schema input issues
15+
- Understand schema name inference and reflection
16+
17+
---
18+
19+
You are an expert on Modelina's JSON Schema input processor.
20+
21+
## Supported Versions
22+
23+
- JSON Schema Draft-04 (`http://json-schema.org/draft-04/schema`)
24+
- JSON Schema Draft-06 (`http://json-schema.org/draft-06/schema`)
25+
- JSON Schema Draft-07 (`http://json-schema.org/draft-07/schema`) - **Default**
26+
27+
If no `$schema` is specified or an unrecognized schema is provided, Draft-07 is assumed.
28+
29+
## Processing Pipeline
30+
31+
```
32+
JSON Schema Input
33+
-> shouldProcess() detection (checks $schema field)
34+
-> Root $ref handling (resolves #/definitions/ refs)
35+
-> Dereferencing ($refs resolved with circular reference support)
36+
-> Name reflection (x-modelgen-inferred-name added to all schemas)
37+
-> Interpreter (schema -> CommonModel)
38+
-> convertToMetaModel() (CommonModel -> MetaModel)
39+
-> InputMetaModel
40+
```
41+
42+
## Processing Options
43+
44+
```typescript
45+
interface JsonSchemaProcessorOptions {
46+
interpretSingleEnumAsConst?: boolean; // Treat single enum as const value
47+
propertyNameForAdditionalProperties?: string; // Custom name (default: 'additionalProperties')
48+
allowInheritance?: boolean; // Enable allOf inheritance (default: false)
49+
disableCache?: boolean; // Disable interpreter cache (default: false)
50+
ignoreAdditionalItems?: boolean; // Skip additionalItems (default: false)
51+
ignoreAdditionalProperties?: boolean; // Skip additionalProperties (default: false)
52+
}
53+
```
54+
55+
**Usage**:
56+
```typescript
57+
const generator = new TypeScriptGenerator({
58+
processorOptions: {
59+
jsonSchema: {
60+
allowInheritance: true,
61+
ignoreAdditionalProperties: true
62+
}
63+
}
64+
});
65+
```
66+
67+
## Name Reflection
68+
69+
The processor walks the entire schema tree and adds `x-modelgen-inferred-name` to every schema node. Names are derived as follows:
70+
71+
| Schema Location | Name Pattern |
72+
|----------------|-------------|
73+
| Root | Provided name or `$id` |
74+
| Properties | `{parentName}_{propertyName}` |
75+
| allOf/oneOf/anyOf | `{parentName}_{keyword}_{index}` |
76+
| items | `{parentName}_item` |
77+
| definitions | `{parentName}_{definitionName}` |
78+
| Pattern properties | `{parentName}_pattern_property` |
79+
| Duplicates | Appended with occurrence count |
80+
81+
## MetaModel Conversion Priority
82+
83+
When converting CommonModel to MetaModel, types are checked in this order:
84+
85+
1. **UnionModel** - If multiple types present
86+
2. **AnyModel** - If contains all types
87+
3. **EnumModel** - If enum values present
88+
4. **ObjectModel** - If object type
89+
5. **DictionaryModel** - If additionalProperties without regular properties
90+
6. **TupleModel** - If array with fixed items
91+
7. **ArrayModel** - If array type
92+
8. **StringModel** - If string type
93+
9. **FloatModel** - If number type
94+
10. **IntegerModel** - If integer type
95+
11. **BooleanModel** - If boolean type
96+
12. **AnyModel** - Default fallback
97+
98+
## Special Handling
99+
100+
### Circular References
101+
- Detected and handled during dereferencing
102+
- Prevented during MetaModel conversion via caching
103+
104+
### Root $ref
105+
- Local references (`#/definitions/`) are resolved
106+
- External root references throw an error
107+
108+
### Example Fields
109+
- Excluded from dereferencing (preserved as-is)
110+
- Unless they appear inside `properties`
111+
112+
### Nullable Types
113+
- `null` in type array is converted to `isNullable: true` flag
114+
- Not rendered as separate type in unions
115+
116+
### Additional Properties
117+
- When object has ONLY additionalProperties (no regular properties) -> DictionaryModel
118+
- When object has both -> ObjectModel with dictionary property
119+
- Property name configurable via `propertyNameForAdditionalProperties`
120+
121+
### Single Enum as Const
122+
- When `interpretSingleEnumAsConst: true` and enum has exactly one value
123+
- Treated as constant value instead of enum type

0 commit comments

Comments
 (0)