agentsml-impl 0.2.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.
Files changed (129) hide show
  1. agentsml_impl/__init__.py +3 -0
  2. agentsml_impl/cli.py +472 -0
  3. agentsml_impl/compiler/__init__.py +1 -0
  4. agentsml_impl/compiler/capabilities.py +330 -0
  5. agentsml_impl/compiler/conditions.py +177 -0
  6. agentsml_impl/compiler/diagnostics.py +112 -0
  7. agentsml_impl/compiler/durations.py +31 -0
  8. agentsml_impl/compiler/expressions.py +123 -0
  9. agentsml_impl/compiler/identifiers.py +60 -0
  10. agentsml_impl/compiler/ir.py +391 -0
  11. agentsml_impl/compiler/limits.py +28 -0
  12. agentsml_impl/compiler/loader.py +83 -0
  13. agentsml_impl/compiler/naming.py +87 -0
  14. agentsml_impl/compiler/planner.py +79 -0
  15. agentsml_impl/compiler/render.py +90 -0
  16. agentsml_impl/compiler/schema_validation.py +121 -0
  17. agentsml_impl/compiler/semantic_validation.py +424 -0
  18. agentsml_impl/protocols/__init__.py +1 -0
  19. agentsml_impl/runtime/__init__.py +1 -0
  20. agentsml_impl/runtime/events.py +59 -0
  21. agentsml_impl/runtime/json_schema.py +138 -0
  22. agentsml_impl/runtime/tools.py +145 -0
  23. agentsml_impl/schemas/agentsml.schema.json +406 -0
  24. agentsml_impl/schemas/v0.1/agentsml.schema.json +628 -0
  25. agentsml_impl/schemas/v0.2/agentsml.schema.json +363 -0
  26. agentsml_impl/schemas/v0.3/agentsml.schema.json +406 -0
  27. agentsml_impl/targets/__init__.py +1 -0
  28. agentsml_impl/targets/a2a/__init__.py +0 -0
  29. agentsml_impl/targets/a2a/adapter.py +94 -0
  30. agentsml_impl/targets/a2a/capabilities.yaml +25 -0
  31. agentsml_impl/targets/ag2/__init__.py +0 -0
  32. agentsml_impl/targets/ag2/adapter.py +655 -0
  33. agentsml_impl/targets/ag2/capabilities.yaml +37 -0
  34. agentsml_impl/targets/ag_ui/__init__.py +0 -0
  35. agentsml_impl/targets/ag_ui/adapter.py +123 -0
  36. agentsml_impl/targets/ag_ui/capabilities.yaml +25 -0
  37. agentsml_impl/targets/agno/__init__.py +0 -0
  38. agentsml_impl/targets/agno/adapter.py +191 -0
  39. agentsml_impl/targets/agno/capabilities.yaml +26 -0
  40. agentsml_impl/targets/ap2/__init__.py +0 -0
  41. agentsml_impl/targets/ap2/adapter.py +84 -0
  42. agentsml_impl/targets/ap2/capabilities.yaml +25 -0
  43. agentsml_impl/targets/base.py +157 -0
  44. agentsml_impl/targets/bedrock_agentcore/__init__.py +0 -0
  45. agentsml_impl/targets/bedrock_agentcore/adapter.py +592 -0
  46. agentsml_impl/targets/bedrock_agentcore/capabilities.yaml +26 -0
  47. agentsml_impl/targets/claude_agent_sdk/__init__.py +0 -0
  48. agentsml_impl/targets/claude_agent_sdk/adapter.py +178 -0
  49. agentsml_impl/targets/claude_agent_sdk/capabilities.yaml +26 -0
  50. agentsml_impl/targets/crewai/__init__.py +0 -0
  51. agentsml_impl/targets/crewai/adapter.py +441 -0
  52. agentsml_impl/targets/crewai/capabilities.yaml +30 -0
  53. agentsml_impl/targets/databricks/__init__.py +0 -0
  54. agentsml_impl/targets/databricks/adapter.py +427 -0
  55. agentsml_impl/targets/databricks/capabilities.yaml +26 -0
  56. agentsml_impl/targets/flowise/__init__.py +0 -0
  57. agentsml_impl/targets/flowise/adapter.py +71 -0
  58. agentsml_impl/targets/flowise/capabilities.yaml +26 -0
  59. agentsml_impl/targets/google_adk/__init__.py +0 -0
  60. agentsml_impl/targets/google_adk/adapter.py +589 -0
  61. agentsml_impl/targets/google_adk/capabilities.yaml +36 -0
  62. agentsml_impl/targets/langchain/__init__.py +1 -0
  63. agentsml_impl/targets/langchain/adapter.py +351 -0
  64. agentsml_impl/targets/langchain/capabilities.yaml +30 -0
  65. agentsml_impl/targets/langflow/__init__.py +0 -0
  66. agentsml_impl/targets/langflow/adapter.py +147 -0
  67. agentsml_impl/targets/langflow/capabilities.yaml +26 -0
  68. agentsml_impl/targets/langgraph/__init__.py +0 -0
  69. agentsml_impl/targets/langgraph/adapter.py +911 -0
  70. agentsml_impl/targets/langgraph/capabilities.yaml +33 -0
  71. agentsml_impl/targets/llamaindex/__init__.py +1 -0
  72. agentsml_impl/targets/llamaindex/adapter.py +406 -0
  73. agentsml_impl/targets/llamaindex/capabilities.yaml +31 -0
  74. agentsml_impl/targets/lyzr/__init__.py +0 -0
  75. agentsml_impl/targets/lyzr/adapter.py +146 -0
  76. agentsml_impl/targets/lyzr/capabilities.yaml +26 -0
  77. agentsml_impl/targets/mastra/__init__.py +0 -0
  78. agentsml_impl/targets/mastra/adapter.py +635 -0
  79. agentsml_impl/targets/mastra/capabilities.yaml +32 -0
  80. agentsml_impl/targets/mcp_server/__init__.py +0 -0
  81. agentsml_impl/targets/mcp_server/adapter.py +141 -0
  82. agentsml_impl/targets/mcp_server/capabilities.yaml +25 -0
  83. agentsml_impl/targets/microsoft_agent_framework/__init__.py +0 -0
  84. agentsml_impl/targets/microsoft_agent_framework/adapter.py +563 -0
  85. agentsml_impl/targets/microsoft_agent_framework/capabilities.yaml +26 -0
  86. agentsml_impl/targets/n8n/__init__.py +0 -0
  87. agentsml_impl/targets/n8n/adapter.py +139 -0
  88. agentsml_impl/targets/n8n/capabilities.yaml +26 -0
  89. agentsml_impl/targets/openai_agents/__init__.py +0 -0
  90. agentsml_impl/targets/openai_agents/adapter.py +175 -0
  91. agentsml_impl/targets/openai_agents/capabilities.yaml +27 -0
  92. agentsml_impl/targets/pydantic_ai/__init__.py +0 -0
  93. agentsml_impl/targets/pydantic_ai/adapter.py +922 -0
  94. agentsml_impl/targets/pydantic_ai/capabilities.yaml +37 -0
  95. agentsml_impl/targets/registry.py +290 -0
  96. agentsml_impl/targets/relevance_ai/__init__.py +0 -0
  97. agentsml_impl/targets/relevance_ai/adapter.py +66 -0
  98. agentsml_impl/targets/relevance_ai/capabilities.yaml +26 -0
  99. agentsml_impl/targets/smolagents/__init__.py +0 -0
  100. agentsml_impl/targets/smolagents/adapter.py +210 -0
  101. agentsml_impl/targets/smolagents/capabilities.yaml +27 -0
  102. agentsml_impl/targets/snowflake_cortex/__init__.py +0 -0
  103. agentsml_impl/targets/snowflake_cortex/adapter.py +167 -0
  104. agentsml_impl/targets/snowflake_cortex/capabilities.yaml +26 -0
  105. agentsml_impl/targets/spring_ai/__init__.py +1 -0
  106. agentsml_impl/targets/spring_ai/adapter.py +626 -0
  107. agentsml_impl/targets/spring_ai/capabilities.yaml +31 -0
  108. agentsml_impl/targets/strands_agents/__init__.py +1 -0
  109. agentsml_impl/targets/strands_agents/adapter.py +309 -0
  110. agentsml_impl/targets/strands_agents/capabilities.yaml +29 -0
  111. agentsml_impl/targets/support_matrix.py +91 -0
  112. agentsml_impl/targets/ucp/__init__.py +0 -0
  113. agentsml_impl/targets/ucp/adapter.py +86 -0
  114. agentsml_impl/targets/ucp/capabilities.yaml +25 -0
  115. agentsml_impl/targets/vercel_ai/__init__.py +1 -0
  116. agentsml_impl/targets/vercel_ai/adapter.py +349 -0
  117. agentsml_impl/targets/vercel_ai/capabilities.yaml +30 -0
  118. agentsml_impl/targets/vertex_agent_engine/__init__.py +0 -0
  119. agentsml_impl/targets/vertex_agent_engine/adapter.py +407 -0
  120. agentsml_impl/targets/vertex_agent_engine/capabilities.yaml +26 -0
  121. agentsml_impl/targets/zapier_agents/__init__.py +0 -0
  122. agentsml_impl/targets/zapier_agents/adapter.py +106 -0
  123. agentsml_impl/targets/zapier_agents/capabilities.yaml +26 -0
  124. agentsml_impl-0.2.0.dist-info/METADATA +109 -0
  125. agentsml_impl-0.2.0.dist-info/RECORD +129 -0
  126. agentsml_impl-0.2.0.dist-info/WHEEL +5 -0
  127. agentsml_impl-0.2.0.dist-info/entry_points.txt +3 -0
  128. agentsml_impl-0.2.0.dist-info/licenses/LICENSE +28 -0
  129. agentsml_impl-0.2.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,123 @@
1
+ """CORE-006: Expression handling — parse ${...} template expressions safely."""
2
+
3
+ from __future__ import annotations
4
+ import re
5
+ from dataclasses import dataclass
6
+ from enum import Enum
7
+ from typing import Optional
8
+
9
+ from agentsml_impl.compiler.conditions import ConditionError, compile_condition
10
+ from agentsml_impl.compiler.diagnostics import DiagCode, DiagnosticSet
11
+
12
+ _DOLLAR_EXPR_RE = re.compile(r"\$\{([^}]+)\}")
13
+ _JINJA_EXPR_RE = re.compile(r"\{\{\s*([^{}]+?)\s*\}\}")
14
+ _TEMPLATE_PATTERNS = (_DOLLAR_EXPR_RE, _JINJA_EXPR_RE)
15
+ _PLAIN_PATH = re.compile(r"[\w\-.\[\]]+")
16
+ _VALID_ROOTS = {"input", "state", "steps", "env", "workflow"}
17
+ _SAFE_SEGMENT = re.compile(r"^([a-zA-Z_][a-zA-Z0-9_-]*|[0-9]+)$")
18
+
19
+
20
+ class ExprKind(str, Enum):
21
+ INPUT = "input"
22
+ STATE = "state"
23
+ STEP = "steps"
24
+ ENV = "env"
25
+ WORKFLOW = "workflow"
26
+ UNKNOWN = "unknown"
27
+
28
+
29
+ @dataclass
30
+ class Expression:
31
+ raw: str
32
+ kind: ExprKind
33
+ path: str
34
+ source_path: str
35
+
36
+
37
+ def parse_expression(raw: str, context_path: str, diagnostics: DiagnosticSet) -> Optional[Expression]:
38
+ """Parse a single ${...} expression string.
39
+
40
+ Returns an Expression or None if the string contains no expression.
41
+ Emits nonportable_expression if expression syntax is not supported.
42
+ """
43
+ stripped = raw.strip()
44
+ m = None
45
+ for pattern in _TEMPLATE_PATTERNS:
46
+ m = pattern.fullmatch(stripped)
47
+ if m:
48
+ break
49
+ if not m:
50
+ # Not a template expression — plain string
51
+ return None
52
+
53
+ inner = m.group(1).strip()
54
+
55
+ if not _PLAIN_PATH.fullmatch(inner):
56
+ try:
57
+ compile_condition(inner)
58
+ except ConditionError:
59
+ pass
60
+ else:
61
+ return Expression(raw=raw, kind=ExprKind.UNKNOWN, path=inner, source_path=context_path)
62
+
63
+ # Reject code-like expressions
64
+ if any(c in inner for c in ("(", ")", "import", "exec", "eval", "__")):
65
+ diagnostics.add_warning(
66
+ DiagCode.NONPORTABLE_EXPRESSION,
67
+ f"Expression '{stripped}' looks like code — only field references are supported.",
68
+ path=context_path,
69
+ recommendation="Use simple dotted field references like ${input.question}.",
70
+ )
71
+ return Expression(raw=raw, kind=ExprKind.UNKNOWN, path=inner, source_path=context_path)
72
+
73
+ parts = inner.split(".", 1)
74
+ root = parts[0]
75
+
76
+ if root not in _VALID_ROOTS:
77
+ diagnostics.add_warning(
78
+ DiagCode.NONPORTABLE_EXPRESSION,
79
+ f"Unknown expression root '{root}' in '${{{inner}}}'. "
80
+ f"Supported roots: {', '.join(sorted(_VALID_ROOTS))}.",
81
+ path=context_path,
82
+ )
83
+ return Expression(raw=raw, kind=ExprKind.UNKNOWN, path=inner, source_path=context_path)
84
+
85
+ normalized = inner.replace("[", ".").replace("]", "")
86
+ if not all(segment and _SAFE_SEGMENT.fullmatch(segment) for segment in normalized.split(".")):
87
+ diagnostics.add_warning(
88
+ DiagCode.NONPORTABLE_EXPRESSION,
89
+ f"Expression '{stripped}' contains unsupported characters.",
90
+ path=context_path,
91
+ )
92
+ return Expression(raw=raw, kind=ExprKind.UNKNOWN, path=inner, source_path=context_path)
93
+
94
+ kind = ExprKind(root) if root in ExprKind._value2member_map_ else ExprKind.UNKNOWN
95
+ return Expression(raw=raw, kind=kind, path=inner, source_path=context_path)
96
+
97
+
98
+ def extract_expressions(value: object, context_path: str, diagnostics: DiagnosticSet) -> list[Expression]:
99
+ """Recursively extract all ${...} expressions from a value (dict, list, or str)."""
100
+ results: list[Expression] = []
101
+ if isinstance(value, str):
102
+ has_dollar = bool(_DOLLAR_EXPR_RE.search(value))
103
+ has_jinja = bool(_JINJA_EXPR_RE.search(value))
104
+ if has_dollar and has_jinja:
105
+ diagnostics.add_warning(
106
+ DiagCode.NONPORTABLE_EXPRESSION,
107
+ "Mixed template styles detected in the same value; use either ${...} or {{...}} consistently.",
108
+ path=context_path,
109
+ recommendation="Choose one template style for this value.",
110
+ )
111
+
112
+ for pattern in _TEMPLATE_PATTERNS:
113
+ for match in pattern.finditer(value):
114
+ expr = parse_expression(match.group(0), context_path, diagnostics)
115
+ if expr:
116
+ results.append(expr)
117
+ elif isinstance(value, dict):
118
+ for k, v in value.items():
119
+ results.extend(extract_expressions(v, f"{context_path}.{k}", diagnostics))
120
+ elif isinstance(value, list):
121
+ for i, v in enumerate(value):
122
+ results.extend(extract_expressions(v, f"{context_path}[{i}]", diagnostics))
123
+ return results
@@ -0,0 +1,60 @@
1
+ """Normalize agent and tool keys into valid Python identifiers before Python code generation."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import replace
6
+
7
+ from agentsml_impl.compiler.ir import AgentSystemIR
8
+ from agentsml_impl.compiler.naming import snake_identifier, unique_identifiers
9
+
10
+
11
+ def python_identifier_ir(ir: AgentSystemIR) -> AgentSystemIR:
12
+ """Return a copy of ``ir`` whose agent and tool keys are safe Python identifiers.
13
+
14
+ Every reference to an agent or tool (agent tool lists, workflow steps, policy
15
+ ``applies_to`` entries) is rewritten to the same identifier, so generators can
16
+ interpolate keys directly into code.
17
+ """
18
+ agent_map = unique_identifiers(ir.agents.keys(), lambda v: snake_identifier(v, prefix="agent"))
19
+ tool_map = unique_identifiers(ir.tools.keys(), lambda v: snake_identifier(v, prefix="tool"))
20
+
21
+ if all(new == old for old, new in agent_map.items()) and all(new == old for old, new in tool_map.items()):
22
+ return ir
23
+
24
+ def rewrite_ref(ref: str) -> str:
25
+ kind, _, name = ref.partition(".")
26
+ if kind == "agents" and name in agent_map:
27
+ return f"agents.{agent_map[name]}"
28
+ if kind == "tools" and name in tool_map:
29
+ return f"tools.{tool_map[name]}"
30
+ return ref
31
+
32
+ agents = {
33
+ agent_map[key]: replace(
34
+ agent,
35
+ key=agent_map[key],
36
+ display_name=agent.display_name or key,
37
+ tools=[tool_map.get(tool, tool) for tool in agent.tools],
38
+ )
39
+ for key, agent in ir.agents.items()
40
+ }
41
+ tools = {tool_map[key]: replace(tool, key=tool_map[key]) for key, tool in ir.tools.items()}
42
+ workflows = {
43
+ key: replace(
44
+ workflow,
45
+ steps=[
46
+ replace(
47
+ step,
48
+ agent=agent_map.get(step.agent, step.agent) if step.agent else step.agent,
49
+ tool=tool_map.get(step.tool, step.tool) if step.tool else step.tool,
50
+ )
51
+ for step in workflow.steps
52
+ ],
53
+ )
54
+ for key, workflow in ir.workflows.items()
55
+ }
56
+ policies = {
57
+ key: replace(policy, applies_to=[rewrite_ref(ref) for ref in policy.applies_to])
58
+ for key, policy in ir.policies.items()
59
+ }
60
+ return replace(ir, agents=agents, tools=tools, workflows=workflows, policies=policies)
@@ -0,0 +1,391 @@
1
+ """CORE-003: IR Data Model — normalized Python objects for AgentsML compiler internals."""
2
+
3
+ from __future__ import annotations
4
+ from dataclasses import dataclass, field
5
+ from typing import Any, Optional
6
+
7
+
8
+ @dataclass
9
+ class MetadataIR:
10
+ name: str
11
+ version: Optional[str] = None
12
+ description: Optional[str] = None
13
+ tags: list[str] = field(default_factory=list)
14
+
15
+ @classmethod
16
+ def from_dict(cls, d: dict) -> "MetadataIR":
17
+ return cls(name=d["name"], version=d.get("version"),
18
+ description=d.get("description"), tags=d.get("tags", []))
19
+
20
+
21
+ @dataclass
22
+ class ProfileIR:
23
+ required: list[str] = field(default_factory=list)
24
+ optional: list[str] = field(default_factory=list)
25
+ extensions: list[str] = field(default_factory=list)
26
+
27
+ @classmethod
28
+ def from_raw(cls, raw: Any) -> "ProfileIR":
29
+ if raw is None:
30
+ return cls()
31
+ if isinstance(raw, list):
32
+ return cls(required=list(raw))
33
+ if isinstance(raw, dict):
34
+ return cls(required=raw.get("required", []),
35
+ optional=raw.get("optional", []),
36
+ extensions=raw.get("extensions", []))
37
+ return cls()
38
+
39
+ def all_profiles(self) -> list[str]:
40
+ return self.required + self.optional + self.extensions
41
+
42
+
43
+ @dataclass
44
+ class ModelIR:
45
+ key: str
46
+ provider: str
47
+ name: str
48
+ version: Optional[str] = None
49
+ parameters: dict[str, Any] = field(default_factory=dict)
50
+ fallbacks: list[str] = field(default_factory=list)
51
+
52
+ @classmethod
53
+ def from_dict(cls, key: str, d: dict) -> "ModelIR":
54
+ return cls(key=key, provider=d["provider"], name=d["name"],
55
+ version=d.get("version"), parameters=d.get("parameters", {}),
56
+ fallbacks=d.get("fallbacks", []))
57
+
58
+
59
+ @dataclass
60
+ class RetryPolicy:
61
+ """Typed step retry policy (Draft 0.3)."""
62
+ max_attempts: Optional[int] = None
63
+ backoff: Optional[str] = None
64
+ initial_interval: Optional[Any] = None
65
+ max_interval: Optional[Any] = None
66
+ on_timeout: Optional[str] = None
67
+ # Unknown keys and values that failed typing (e.g. non-integer max_attempts).
68
+ extras: dict[str, Any] = field(default_factory=dict)
69
+
70
+ _KNOWN = ("max_attempts", "backoff", "initial_interval", "max_interval", "on_timeout")
71
+
72
+ @classmethod
73
+ def from_raw(cls, raw: Any) -> Optional["RetryPolicy"]:
74
+ if not isinstance(raw, dict):
75
+ return None
76
+ extras = {k: v for k, v in raw.items() if k not in cls._KNOWN}
77
+ max_attempts = raw.get("max_attempts")
78
+ if max_attempts is not None and (
79
+ isinstance(max_attempts, bool) or not isinstance(max_attempts, int)
80
+ ):
81
+ extras["max_attempts"] = max_attempts
82
+ max_attempts = None
83
+ return cls(max_attempts=max_attempts, backoff=raw.get("backoff"),
84
+ initial_interval=raw.get("initial_interval"),
85
+ max_interval=raw.get("max_interval"),
86
+ on_timeout=raw.get("on_timeout"), extras=extras)
87
+
88
+ def valid_max_attempts(self) -> Optional[int]:
89
+ """max_attempts when it is an int >= 1, else None."""
90
+ m = self.max_attempts
91
+ return m if isinstance(m, int) and not isinstance(m, bool) and m >= 1 else None
92
+
93
+
94
+ @dataclass
95
+ class ReasoningConfig:
96
+ """Agent-level reasoning configuration (Draft 0.3)."""
97
+ effort: Optional[str] = None
98
+ budget_tokens: Optional[int] = None
99
+ expose_trace: Optional[bool] = None
100
+
101
+ @classmethod
102
+ def from_raw(cls, raw: Any) -> Optional["ReasoningConfig"]:
103
+ if not isinstance(raw, dict):
104
+ return None
105
+ return cls(effort=raw.get("effort"), budget_tokens=raw.get("budget_tokens"),
106
+ expose_trace=raw.get("expose_trace"))
107
+
108
+
109
+ @dataclass
110
+ class ToolIR:
111
+ key: str
112
+ description: str
113
+ source: str
114
+ input_schema: Optional[dict] = None
115
+ output_schema: Optional[dict] = None
116
+ auth: Optional[dict] = None
117
+ permissions: Optional[dict] = None
118
+ side_effect: Optional[str] = None
119
+ timeout: Optional[Any] = None
120
+ error_policy: Optional[dict] = None
121
+ mcp_server: Optional[str] = None
122
+ mcp_tool_name: Optional[str] = None
123
+ needs_approval: Optional[bool] = None
124
+ approval_mode: Optional[str] = None
125
+
126
+ @classmethod
127
+ def from_dict(cls, key: str, d: dict) -> "ToolIR":
128
+ return cls(key=key, description=d.get("description", ""),
129
+ source=d.get("source", "local.function"),
130
+ input_schema=d.get("input_schema"), output_schema=d.get("output_schema"),
131
+ auth=d.get("auth"), permissions=d.get("permissions"),
132
+ side_effect=d.get("side_effect"), timeout=d.get("timeout"),
133
+ error_policy=d.get("error_policy"),
134
+ mcp_server=d.get("mcp_server"), mcp_tool_name=d.get("mcp_tool_name"),
135
+ needs_approval=d.get("needs_approval"),
136
+ approval_mode=d.get("approval_mode"))
137
+
138
+ def is_mcp(self) -> bool: return self.source == "mcp.tool"
139
+ def is_local(self) -> bool: return self.source == "local.function"
140
+ def is_openapi(self) -> bool: return self.source == "openapi.operation"
141
+ def has_dangerous_side_effect(self) -> bool:
142
+ return self.side_effect in ("payment", "delete", "write", "browser", "external")
143
+
144
+
145
+ @dataclass
146
+ class ResourceIR:
147
+ key: str
148
+ description: Optional[str] = None
149
+ source: Optional[str] = None
150
+ schema: Optional[dict] = None
151
+ auth: Optional[dict] = None
152
+ permissions: Optional[dict] = None
153
+
154
+ @classmethod
155
+ def from_dict(cls, key: str, d: dict) -> "ResourceIR":
156
+ return cls(key=key, description=d.get("description"), source=d.get("source"),
157
+ schema=d.get("schema"), auth=d.get("auth"), permissions=d.get("permissions"))
158
+
159
+
160
+ @dataclass
161
+ class PromptIR:
162
+ key: str
163
+ template: str
164
+ description: Optional[str] = None
165
+ input_schema: Optional[dict] = None
166
+
167
+ @classmethod
168
+ def from_dict(cls, key: str, d: dict) -> "PromptIR":
169
+ return cls(key=key, template=d["template"], description=d.get("description"),
170
+ input_schema=d.get("input_schema"))
171
+
172
+
173
+ @dataclass
174
+ class AgentIR:
175
+ key: str
176
+ model: str
177
+ instructions: str
178
+ description: Optional[str] = None
179
+ role: Optional[str] = None
180
+ tools: list[str] = field(default_factory=list)
181
+ resources: list[str] = field(default_factory=list)
182
+ prompts: list[str] = field(default_factory=list)
183
+ memory: Optional[dict] = None
184
+ knowledge: Optional[dict] = None
185
+ output_schema: Optional[dict] = None
186
+ policies: list[str] = field(default_factory=list)
187
+ display_name: Optional[str] = None
188
+ reasoning: Optional[ReasoningConfig] = None
189
+
190
+ @classmethod
191
+ def from_dict(cls, key: str, d: dict) -> "AgentIR":
192
+ return cls(key=key, model=d["model"], instructions=d["instructions"],
193
+ description=d.get("description"), role=d.get("role"),
194
+ tools=d.get("tools", []), resources=d.get("resources", []),
195
+ prompts=d.get("prompts", []), memory=d.get("memory"),
196
+ knowledge=d.get("knowledge"), output_schema=d.get("output_schema"),
197
+ policies=d.get("policies", []),
198
+ reasoning=ReasoningConfig.from_raw(d.get("reasoning")))
199
+
200
+
201
+ @dataclass
202
+ class EdgeIR:
203
+ from_step: str
204
+ to_step: str
205
+ condition: Optional[Any] = None
206
+ label: Optional[str] = None
207
+
208
+ @classmethod
209
+ def from_dict(cls, d: dict) -> "EdgeIR":
210
+ return cls(from_step=d["from"], to_step=d["to"],
211
+ condition=d.get("condition"), label=d.get("label"))
212
+
213
+
214
+ @dataclass
215
+ class StepFallback:
216
+ """Draft 0.3 step `fallback`: a static output value and/or a fallback model reference."""
217
+ output: Any = None
218
+ model: Optional[str] = None
219
+ has_output: bool = False
220
+
221
+ @classmethod
222
+ def from_raw(cls, raw: Any) -> Optional["StepFallback"]:
223
+ if not isinstance(raw, dict):
224
+ return None
225
+ return cls(output=raw.get("output"), model=raw.get("model"), has_output="output" in raw)
226
+
227
+
228
+ @dataclass
229
+ class StepIR:
230
+ id: str
231
+ agent: Optional[str] = None
232
+ tool: Optional[str] = None
233
+ workflow: Optional[str] = None
234
+ a2a_agent: Optional[str] = None
235
+ skill: Optional[str] = None
236
+ input: Optional[Any] = None
237
+ output: Optional[Any] = None
238
+ condition: Optional[Any] = None
239
+ depends_on: list[str] = field(default_factory=list)
240
+ retry: Optional[RetryPolicy] = None
241
+ timeout: Optional[Any] = None
242
+ approval: Optional[Any] = None
243
+ events: list[Any] = field(default_factory=list)
244
+ fallback: Optional[StepFallback] = None
245
+
246
+ @classmethod
247
+ def from_dict(cls, d: dict) -> "StepIR":
248
+ return cls(id=d["id"], agent=d.get("agent"), tool=d.get("tool"),
249
+ workflow=d.get("workflow"), a2a_agent=d.get("a2a_agent"),
250
+ skill=d.get("skill"),
251
+ input=d.get("input"), output=d.get("output"),
252
+ condition=d.get("condition"), depends_on=d.get("depends_on", []),
253
+ retry=RetryPolicy.from_raw(d.get("retry")), timeout=d.get("timeout"),
254
+ approval=d.get("approval"), events=d.get("events", []),
255
+ fallback=StepFallback.from_raw(d.get("fallback")))
256
+
257
+ def primary_targets(self) -> list[str]:
258
+ return [t for t in ("agent", "tool", "workflow", "a2a_agent") if getattr(self, t) is not None]
259
+
260
+ def is_approval_only(self) -> bool:
261
+ return not self.primary_targets() and self.approval is not None
262
+
263
+
264
+ @dataclass
265
+ class WorkflowIR:
266
+ key: str
267
+ steps: list[StepIR] = field(default_factory=list)
268
+ edges: list[EdgeIR] = field(default_factory=list)
269
+ description: Optional[str] = None
270
+ input_schema: Optional[dict] = None
271
+ output_schema: Optional[dict] = None
272
+ state: Optional[dict] = None
273
+ error_policy: Optional[dict] = None
274
+
275
+ @classmethod
276
+ def from_dict(cls, key: str, d: dict) -> "WorkflowIR":
277
+ return cls(key=key,
278
+ steps=[StepIR.from_dict(s) for s in d.get("steps", [])],
279
+ edges=[EdgeIR.from_dict(e) for e in d.get("edges", [])],
280
+ description=d.get("description"), input_schema=d.get("input_schema"),
281
+ output_schema=d.get("output_schema"), state=d.get("state"),
282
+ error_policy=d.get("error_policy"))
283
+
284
+ def step_ids(self) -> set[str]:
285
+ return {s.id for s in self.steps}
286
+
287
+ def has_cycles(self) -> bool:
288
+ graph: dict[str, list[str]] = {s.id: [] for s in self.steps}
289
+ for e in self.edges:
290
+ if e.from_step in graph:
291
+ graph[e.from_step].append(e.to_step)
292
+ visited: set[str] = set()
293
+ rec_stack: set[str] = set()
294
+
295
+ def dfs(node: str) -> bool:
296
+ visited.add(node)
297
+ rec_stack.add(node)
298
+ for nb in graph.get(node, []):
299
+ if nb not in visited:
300
+ if dfs(nb): return True
301
+ elif nb in rec_stack:
302
+ return True
303
+ rec_stack.discard(node)
304
+ return False
305
+
306
+ return any(dfs(n) for n in list(graph) if n not in visited)
307
+
308
+
309
+ @dataclass
310
+ class PolicyIR:
311
+ key: str
312
+ description: Optional[str] = None
313
+ applies_to: list[str] = field(default_factory=list)
314
+ permissions: Optional[dict] = None
315
+ guardrails: Optional[dict] = None
316
+ approval: Optional[dict] = None
317
+ audit: Optional[dict] = None
318
+
319
+ @classmethod
320
+ def from_dict(cls, key: str, d: dict) -> "PolicyIR":
321
+ return cls(key=key, description=d.get("description"),
322
+ applies_to=d.get("applies_to", []),
323
+ permissions=d.get("permissions"), guardrails=d.get("guardrails"),
324
+ approval=d.get("approval"), audit=d.get("audit"))
325
+
326
+
327
+ @dataclass
328
+ class DeploymentIR:
329
+ key: str
330
+ raw: dict = field(default_factory=dict)
331
+
332
+ @classmethod
333
+ def from_dict(cls, key: str, d: dict) -> "DeploymentIR":
334
+ return cls(key=key, raw=d)
335
+
336
+
337
+ @dataclass
338
+ class AgentSystemIR:
339
+ """Normalized top-level AgentsML document."""
340
+ version: str
341
+ kind: str
342
+ metadata: MetadataIR
343
+ profiles: ProfileIR
344
+ models: dict[str, ModelIR] = field(default_factory=dict)
345
+ tools: dict[str, ToolIR] = field(default_factory=dict)
346
+ resources: dict[str, ResourceIR] = field(default_factory=dict)
347
+ prompts: dict[str, PromptIR] = field(default_factory=dict)
348
+ agents: dict[str, AgentIR] = field(default_factory=dict)
349
+ workflows: dict[str, WorkflowIR] = field(default_factory=dict)
350
+ schemas: dict[str, dict] = field(default_factory=dict)
351
+ policies: dict[str, PolicyIR] = field(default_factory=dict)
352
+ deployments: dict[str, DeploymentIR] = field(default_factory=dict)
353
+ events: dict[str, Any] = field(default_factory=dict)
354
+ mcp_servers: dict[str, dict[str, Any]] = field(default_factory=dict)
355
+ a2a_agents: dict[str, dict[str, Any]] = field(default_factory=dict)
356
+ a2a_server: Optional[dict[str, Any]] = None
357
+ ui: Optional[dict[str, Any]] = None
358
+ extras: dict[str, Any] = field(default_factory=dict)
359
+
360
+ _KNOWN_KEYS = frozenset({
361
+ "agentsml", "kind", "metadata", "profiles", "models", "tools",
362
+ "resources", "prompts", "agents", "workflows", "schemas",
363
+ "policies", "deployments",
364
+ })
365
+
366
+ @classmethod
367
+ def from_dict(cls, doc: dict[str, Any]) -> "AgentSystemIR":
368
+ # Keep stable extension blocks in extras for compatibility with existing
369
+ # planner/validation/adapter code that still reads them there.
370
+ extras = {k: v for k, v in doc.items() if k not in cls._KNOWN_KEYS}
371
+ return cls(
372
+ version=doc.get("agentsml", "0.1"),
373
+ kind=doc.get("kind", "AgentSystem"),
374
+ metadata=MetadataIR.from_dict(doc.get("metadata", {"name": "unknown"})),
375
+ profiles=ProfileIR.from_raw(doc.get("profiles")),
376
+ models={k: ModelIR.from_dict(k, v) for k, v in doc.get("models", {}).items()},
377
+ tools={k: ToolIR.from_dict(k, v) for k, v in doc.get("tools", {}).items()},
378
+ resources={k: ResourceIR.from_dict(k, v) for k, v in doc.get("resources", {}).items()},
379
+ prompts={k: PromptIR.from_dict(k, v) for k, v in doc.get("prompts", {}).items()},
380
+ agents={k: AgentIR.from_dict(k, v) for k, v in doc.get("agents", {}).items()},
381
+ workflows={k: WorkflowIR.from_dict(k, v) for k, v in doc.get("workflows", {}).items()},
382
+ schemas=doc.get("schemas", {}),
383
+ policies={k: PolicyIR.from_dict(k, v) for k, v in doc.get("policies", {}).items()},
384
+ deployments={k: DeploymentIR.from_dict(k, v) for k, v in doc.get("deployments", {}).items()},
385
+ events=doc.get("events", {}) or {},
386
+ mcp_servers=doc.get("mcp_servers", {}) or {},
387
+ a2a_agents=doc.get("a2a_agents", {}) or {},
388
+ a2a_server=doc.get("a2a_server"),
389
+ ui=doc.get("ui"),
390
+ extras=extras,
391
+ )
@@ -0,0 +1,28 @@
1
+ """CORE-LIMIT: hard ceiling on the tokens a generated model call may request.
2
+
3
+ The targets AgentsML compiles for are frequently served by local, single-GPU
4
+ runtimes whose context window is 8192 tokens. A generated project that asks a
5
+ model for more completion tokens than the window allows fails at runtime, so
6
+ the compiler never emits a ``max_tokens`` above the ceiling and reports the
7
+ clamp as a diagnostic.
8
+ """
9
+
10
+ from __future__ import annotations
11
+
12
+ from typing import Any
13
+
14
+ MAX_MODEL_TOKENS = 8192
15
+ """Upper bound for the completion tokens a generated model call may request."""
16
+
17
+
18
+ def clamp_max_tokens(value: Any) -> tuple[Any, bool]:
19
+ """Return ``(value, clamped)`` for a requested ``max_tokens`` value.
20
+
21
+ Non-numeric values are left untouched: the target SDK is the authority on
22
+ what it accepts.
23
+ """
24
+ if isinstance(value, bool) or not isinstance(value, (int, float)):
25
+ return value, False
26
+ if value <= MAX_MODEL_TOKENS:
27
+ return value, False
28
+ return MAX_MODEL_TOKENS, True
@@ -0,0 +1,83 @@
1
+ """CORE-001: YAML Loader — load AgentsML YAML documents with helpful errors."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+ from typing import Any
7
+
8
+ import yaml
9
+
10
+ from agentsml_impl.compiler.diagnostics import DiagCode, DiagnosticSet, Severity, Diagnostic
11
+
12
+
13
+ class LoadError(Exception):
14
+ """Raised when a document cannot be loaded."""
15
+
16
+
17
+ def load_yaml(path: Path, diagnostics: DiagnosticSet | None = None) -> dict[str, Any]:
18
+ """Load an AgentsML YAML file and return the parsed document as a dict.
19
+
20
+ Args:
21
+ path: Path to the AgentsML YAML file.
22
+ diagnostics: Optional DiagnosticSet to accumulate errors instead of raising.
23
+
24
+ Returns:
25
+ Parsed document dict.
26
+
27
+ Raises:
28
+ LoadError: If the file cannot be loaded and no diagnostics set is given.
29
+ """
30
+ ds = DiagnosticSet() if diagnostics is None else diagnostics
31
+
32
+ if not path.exists():
33
+ msg = f"File not found: {path}"
34
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
35
+ if diagnostics is None:
36
+ raise LoadError(msg)
37
+ return {}
38
+
39
+ try:
40
+ size = path.stat().st_size
41
+ except OSError:
42
+ size = -1
43
+
44
+ if size == 0:
45
+ msg = f"File is empty: {path}"
46
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
47
+ if diagnostics is None:
48
+ raise LoadError(msg)
49
+ return {}
50
+
51
+ try:
52
+ raw = path.read_text(encoding="utf-8")
53
+ except OSError as exc:
54
+ msg = f"Cannot read file {path}: {exc}"
55
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
56
+ if diagnostics is None:
57
+ raise LoadError(msg) from exc
58
+ return {}
59
+
60
+ try:
61
+ doc = yaml.safe_load(raw)
62
+ except yaml.YAMLError as exc:
63
+ msg = f"YAML parse error in {path}: {exc}"
64
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
65
+ if diagnostics is None:
66
+ raise LoadError(msg) from exc
67
+ return {}
68
+
69
+ if doc is None:
70
+ msg = f"YAML document is null (empty content): {path}"
71
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
72
+ if diagnostics is None:
73
+ raise LoadError(msg)
74
+ return {}
75
+
76
+ if not isinstance(doc, dict):
77
+ msg = f"YAML root must be an object/mapping, got {type(doc).__name__}: {path}"
78
+ ds.add_fatal(DiagCode.GENERATION_FAILED, msg, path=str(path))
79
+ if diagnostics is None:
80
+ raise LoadError(msg)
81
+ return {}
82
+
83
+ return doc