machine-internet 0.1.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 (33) hide show
  1. machine_internet/__init__.py +0 -0
  2. machine_internet/ai/__init__.py +0 -0
  3. machine_internet/ai/client.py +146 -0
  4. machine_internet/auth/__init__.py +0 -0
  5. machine_internet/auth/injector.py +102 -0
  6. machine_internet/cli.py +361 -0
  7. machine_internet/condensation/__init__.py +0 -0
  8. machine_internet/condensation/condenser.py +262 -0
  9. machine_internet/condensation/eval.py +131 -0
  10. machine_internet/config.py +26 -0
  11. machine_internet/discovery/__init__.py +0 -0
  12. machine_internet/discovery/errors.py +60 -0
  13. machine_internet/discovery/openapi.py +281 -0
  14. machine_internet/discovery/schema.py +104 -0
  15. machine_internet/discovery/traffic.py +433 -0
  16. machine_internet/examples/archive_org.json +127 -0
  17. machine_internet/examples/bundlephobia.json +200 -0
  18. machine_internet/examples/caniuse.json +133 -0
  19. machine_internet/examples/crates_io.json +273 -0
  20. machine_internet/examples/deps_dev.json +332 -0
  21. machine_internet/examples/hacker_news.json +86 -0
  22. machine_internet/examples/huggingface.json +56 -0
  23. machine_internet/examples/npm_trends.json +154 -0
  24. machine_internet/examples/ossinsight.json +98 -0
  25. machine_internet/examples/regex101.json +126 -0
  26. machine_internet/serving/__init__.py +0 -0
  27. machine_internet/serving/executor.py +140 -0
  28. machine_internet/serving/mcp_server.py +158 -0
  29. machine_internet-0.1.0.dist-info/METADATA +201 -0
  30. machine_internet-0.1.0.dist-info/RECORD +33 -0
  31. machine_internet-0.1.0.dist-info/WHEEL +4 -0
  32. machine_internet-0.1.0.dist-info/entry_points.txt +2 -0
  33. machine_internet-0.1.0.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,262 @@
1
+ from __future__ import annotations
2
+ import json
3
+ import re
4
+ from datetime import datetime, timezone
5
+
6
+ from ..discovery.errors import LLMEmptySchemaError, LLMInvalidResponseError, LLMQuotaError
7
+ from ..discovery.schema import (
8
+ AgentTool,
9
+ AuthScheme,
10
+ CondensedSchema,
11
+ EndpointParameter,
12
+ EndpointMapping,
13
+ ParameterLocation,
14
+ ParameterMapping,
15
+ RawSchema,
16
+ ToolParameter,
17
+ )
18
+ from ..ai.client import get_ai_client
19
+
20
+ _SYSTEM = """You are an expert API designer specialising in making APIs accessible to AI agents.
21
+
22
+ Given a raw API schema, collapse its endpoints into a minimal, high-quality set of agent tools.
23
+
24
+ Principles:
25
+ - 10–15 tools maximum. Fewer is better.
26
+ - Each tool represents a meaningful agent action, not an HTTP endpoint.
27
+ - Collapse related CRUD into unified tools where sensible.
28
+ - Name tools with verb_noun: get_customer, create_order, search_products.
29
+ - Write descriptions that tell agents exactly when to use the tool.
30
+ - Drop internal/system parameters agents don't control."""
31
+
32
+
33
+ def _extract_json(text: str) -> dict:
34
+ """Extract the first valid JSON object from a model response."""
35
+ text = re.sub(r"^```(?:json)?\s*", "", text.strip())
36
+ text = re.sub(r"\s*```$", "", text)
37
+
38
+ try:
39
+ return json.loads(text)
40
+ except json.JSONDecodeError:
41
+ pass
42
+
43
+ start = text.find("{")
44
+ if start == -1:
45
+ raise ValueError("No JSON object found in model response")
46
+
47
+ end = _find_json_end(text, start)
48
+ if end == -1:
49
+ raise ValueError(f"Truncated JSON in model response: {text[:200]}")
50
+
51
+ return json.loads(text[start:end + 1])
52
+
53
+
54
+ def _find_json_end(text: str, start: int) -> int:
55
+ """Walk text from `start`, tracking string literals so braces inside strings are ignored."""
56
+ i = start
57
+ depth = 0
58
+ in_string = False
59
+ escape = False
60
+ while i < len(text):
61
+ ch = text[i]
62
+ if escape:
63
+ escape = False
64
+ elif in_string:
65
+ if ch == "\\":
66
+ escape = True
67
+ elif ch == '"':
68
+ in_string = False
69
+ else:
70
+ if ch == '"':
71
+ in_string = True
72
+ elif ch == "{":
73
+ depth += 1
74
+ elif ch == "}":
75
+ depth -= 1
76
+ if depth == 0:
77
+ return i
78
+ i += 1
79
+ return -1
80
+
81
+
82
+ _MAX_ENDPOINTS = 40
83
+
84
+
85
+ async def condense(raw: RawSchema, source_url: str = "") -> CondensedSchema:
86
+ endpoints = raw.endpoints[:_MAX_ENDPOINTS]
87
+
88
+ endpoints_data = [
89
+ {
90
+ "path": ep.path,
91
+ "method": ep.method,
92
+ "summary": ep.summary,
93
+ "description": ep.description,
94
+ "tags": ep.tags,
95
+ "parameters": [
96
+ {
97
+ "name": p.name,
98
+ "location": p.location.value,
99
+ "required": p.required,
100
+ "type": p.type,
101
+ "description": p.description,
102
+ }
103
+ for p in ep.parameters
104
+ ],
105
+ }
106
+ for ep in endpoints
107
+ ]
108
+
109
+ prompt = f"""Service: {raw.title}
110
+ Description: {raw.description}
111
+ Base URL: {raw.base_url}
112
+ Endpoint count: {len(endpoints)}
113
+
114
+ Endpoints:
115
+ {json.dumps(endpoints_data, indent=2)}
116
+
117
+ Return condensed schema as JSON only:
118
+ {{
119
+ "service_name": "snake_case_name",
120
+ "service_description": "One sentence describing this service.",
121
+ "tools": [
122
+ {{
123
+ "name": "verb_noun",
124
+ "description": "Precise description for agent.",
125
+ "parameters": [
126
+ {{"name": "p", "type": "string", "required": true, "description": "..."}}
127
+ ],
128
+ "endpoint_mappings": [
129
+ {{
130
+ "method": "GET",
131
+ "path": "/api/path/{{id}}",
132
+ "parameter_mappings": [
133
+ {{"tool_param": "p", "endpoint_param": "real_p", "location": "path"}}
134
+ ],
135
+ "static_params": {{}}
136
+ }}
137
+ ],
138
+ "response_fields": null
139
+ }}
140
+ ]
141
+ }}
142
+
143
+ Return ONLY valid JSON. Maximum 15 tools."""
144
+
145
+ try:
146
+ raw_text = await get_ai_client().generate(
147
+ prompt,
148
+ system=_SYSTEM,
149
+ max_tokens=32768,
150
+ )
151
+ except RuntimeError as exc:
152
+ if "exhausted" in str(exc).lower():
153
+ raise LLMQuotaError() from exc
154
+ raise
155
+
156
+ try:
157
+ data = _extract_json(raw_text)
158
+ except (ValueError, json.JSONDecodeError) as exc:
159
+ raise LLMInvalidResponseError() from exc
160
+
161
+ tools: list[AgentTool] = []
162
+ for t in data.get("tools", []):
163
+ # One malformed tool from the LLM should not sink the whole run
164
+ try:
165
+ tools.append(_build_tool(t))
166
+ except (KeyError, TypeError, ValueError) as exc:
167
+ print(f" [condense] skipped malformed tool {t.get('name', '?') if isinstance(t, dict) else '?'}: {str(exc)[:100]}")
168
+
169
+ tools = [_repair_tool(t, raw) for t in tools]
170
+ if not tools:
171
+ raise LLMEmptySchemaError()
172
+
173
+ auth_type = raw.auth_schemes[0] if raw.auth_schemes else AuthScheme.NONE
174
+
175
+ return CondensedSchema(
176
+ base_url=raw.base_url,
177
+ service_name=data.get("service_name", raw.title.lower().replace(" ", "_")),
178
+ service_description=data.get("service_description", raw.description),
179
+ tools=tools,
180
+ auth_type=auth_type,
181
+ created_at=datetime.now(timezone.utc).isoformat(),
182
+ source_url=source_url,
183
+ static_headers=raw.static_headers,
184
+ static_query=raw.static_query,
185
+ )
186
+
187
+
188
+ def _build_tool(t: dict) -> AgentTool:
189
+ params = [
190
+ ToolParameter(
191
+ name=p["name"],
192
+ type=p.get("type", "string"),
193
+ required=p.get("required", False),
194
+ description=p.get("description", ""),
195
+ default=p.get("default"),
196
+ )
197
+ for p in t.get("parameters", [])
198
+ ]
199
+ mappings = [
200
+ EndpointMapping(
201
+ method=em["method"],
202
+ path=em["path"],
203
+ parameter_mappings=[
204
+ ParameterMapping(
205
+ tool_param=pm["tool_param"],
206
+ endpoint_param=pm["endpoint_param"],
207
+ location=ParameterLocation(pm.get("location", "query")),
208
+ )
209
+ for pm in em.get("parameter_mappings", [])
210
+ ],
211
+ static_params=em.get("static_params", {}),
212
+ )
213
+ for em in t.get("endpoint_mappings", [])
214
+ ]
215
+ response_fields = t.get("response_fields")
216
+ if isinstance(response_fields, list):
217
+ response_fields = [f["name"] if isinstance(f, dict) and "name" in f else str(f) for f in response_fields]
218
+ else:
219
+ response_fields = None
220
+ return AgentTool(
221
+ name=t["name"],
222
+ description=t.get("description", ""),
223
+ parameters=params,
224
+ endpoint_mappings=mappings,
225
+ response_fields=response_fields or None,
226
+ )
227
+
228
+
229
+ _PLACEHOLDER_RE = re.compile(r"\{(\w+)\}")
230
+
231
+
232
+ def _repair_tool(tool: AgentTool, raw: RawSchema) -> AgentTool:
233
+ """Fix the most common LLM slip: a {placeholder} in a path that no tool parameter fills.
234
+
235
+ If discovery observed a value for it, bake that value into the path. Otherwise expose
236
+ it as a required tool parameter so the agent can supply it, instead of calling a URL
237
+ with a literal "{placeholder}" in it.
238
+ """
239
+ raw_params: dict[tuple[str, str], dict[str, EndpointParameter]] = {
240
+ (ep.method.upper(), ep.path): {p.name: p for p in ep.parameters} for ep in raw.endpoints
241
+ }
242
+ raw_formats = {(ep.method.upper(), ep.path): ep.body_format for ep in raw.endpoints}
243
+ for m in tool.endpoint_mappings:
244
+ m.body_format = raw_formats.get((m.method.upper(), m.path), m.body_format)
245
+ tool_param_names = {p.name for p in tool.parameters}
246
+ for m in tool.endpoint_mappings:
247
+ filled = {pm.endpoint_param for pm in m.parameter_mappings if pm.location == ParameterLocation.PATH}
248
+ for name in _PLACEHOLDER_RE.findall(m.path):
249
+ if name in filled:
250
+ continue
251
+ observed = raw_params.get((m.method.upper(), m.path), {}).get(name)
252
+ if observed is not None and observed.default not in (None, ""):
253
+ m.path = m.path.replace("{" + name + "}", str(observed.default))
254
+ continue
255
+ if name not in tool_param_names:
256
+ desc = observed.description if observed and observed.description else f"Value for {{{name}}} in the URL path."
257
+ tool.parameters.append(ToolParameter(name=name, type="string", required=True, description=desc))
258
+ tool_param_names.add(name)
259
+ m.parameter_mappings.append(
260
+ ParameterMapping(tool_param=name, endpoint_param=name, location=ParameterLocation.PATH)
261
+ )
262
+ return tool
@@ -0,0 +1,131 @@
1
+ from __future__ import annotations
2
+ import json
3
+ from dataclasses import dataclass, field
4
+ from pathlib import Path
5
+ from typing import Optional
6
+
7
+ from ..discovery.schema import RawSchema
8
+ from .condenser import condense
9
+
10
+ GROUND_TRUTH_DIR = Path(__file__).parent.parent.parent / "evals" / "ground_truth"
11
+
12
+
13
+ @dataclass
14
+ class EvalResult:
15
+ service: str
16
+ source_file: str
17
+ tool_count: int
18
+ target_tool_count: int
19
+ generated_tools: list[str]
20
+ ground_truth_tools: list[str]
21
+ matched: list[str] # ground truth tools that were covered
22
+ unmatched: list[str] # ground truth tools that were not covered
23
+ coverage_score: float # matched / total ground truth
24
+ conciseness_score: float
25
+ overall_score: float
26
+ errors: list[str] = field(default_factory=list)
27
+
28
+
29
+ def _nouns(tool_name: str) -> set[str]:
30
+ """All meaningful words in a tool name (strip common verbs to focus on subject nouns)."""
31
+ verbs = {"get", "list", "create", "add", "update", "edit", "delete", "remove",
32
+ "manage", "set", "fetch", "retrieve", "search", "find", "check",
33
+ "inspect", "simulate", "prompt", "send", "place", "put"}
34
+ words = set(tool_name.lower().split("_"))
35
+ nouns = words - verbs
36
+ return nouns if nouns else words # fall back to all words if no nouns remain
37
+
38
+
39
+ def _covers(gt_tool: str, generated_names: set[str]) -> bool:
40
+ """True if any generated tool semantically covers the ground truth tool."""
41
+ if gt_tool in generated_names:
42
+ return True
43
+ gt_nouns = _nouns(gt_tool)
44
+ for gen in generated_names:
45
+ gen_nouns = _nouns(gen)
46
+ if gt_nouns & gen_nouns: # any noun overlap
47
+ return True
48
+ return False
49
+
50
+
51
+ async def run_eval(schema_file: Optional[Path] = None) -> list[EvalResult]:
52
+ files = [schema_file] if schema_file else sorted(GROUND_TRUTH_DIR.glob("*.json"))
53
+ results = []
54
+ for f in files:
55
+ results.append(await _eval_single(f))
56
+ return results
57
+
58
+
59
+ async def _eval_single(path: Path) -> EvalResult:
60
+ try:
61
+ data = json.loads(path.read_text(encoding="utf-8"))
62
+ raw = RawSchema(**data.get("raw_schema", data))
63
+ ground_truth: list[str] = data.get("ground_truth_tools", [])
64
+
65
+ condensed = await condense(raw)
66
+ generated = [t.name for t in condensed.tools]
67
+ generated_set = set(generated)
68
+
69
+ matched = [gt for gt in ground_truth if _covers(gt, generated_set)]
70
+ unmatched = [gt for gt in ground_truth if not _covers(gt, generated_set)]
71
+
72
+ coverage = len(matched) / max(len(ground_truth), 1)
73
+ conciseness = 1.0 if len(generated) <= 15 else max(0.0, 1 - (len(generated) - 15) / 10)
74
+ overall = 0.6 * coverage + 0.4 * conciseness
75
+
76
+ return EvalResult(
77
+ service=raw.title,
78
+ source_file=path.name,
79
+ tool_count=len(generated),
80
+ target_tool_count=len(ground_truth),
81
+ generated_tools=generated,
82
+ ground_truth_tools=ground_truth,
83
+ matched=matched,
84
+ unmatched=unmatched,
85
+ coverage_score=coverage,
86
+ conciseness_score=conciseness,
87
+ overall_score=overall,
88
+ )
89
+ except Exception as exc:
90
+ return EvalResult(
91
+ service=path.stem,
92
+ source_file=path.name,
93
+ tool_count=0,
94
+ target_tool_count=0,
95
+ generated_tools=[],
96
+ ground_truth_tools=[],
97
+ matched=[],
98
+ unmatched=[],
99
+ coverage_score=0.0,
100
+ conciseness_score=0.0,
101
+ overall_score=0.0,
102
+ errors=[str(exc)],
103
+ )
104
+
105
+
106
+ def print_report(results: list[EvalResult]) -> None:
107
+ SEP = "-" * 64
108
+ print(f"\n{'Condensation Eval':^64}")
109
+ print(SEP)
110
+ for r in results:
111
+ if r.errors:
112
+ print(f" ERROR {r.source_file}")
113
+ for e in r.errors:
114
+ print(f" {e}")
115
+ print()
116
+ continue
117
+ grade = "PASS" if r.overall_score >= 0.7 else "FAIL"
118
+ mark = "[PASS]" if grade == "PASS" else "[FAIL]"
119
+ print(f"\n{mark} {r.service} ({r.source_file})")
120
+ print(f" Generated : {r.tool_count} tools | Ground truth : {r.target_tool_count} concepts")
121
+ print(f" Coverage : {r.coverage_score:.0%} Conciseness : {r.conciseness_score:.0%} Overall : {r.overall_score:.0%}")
122
+ if r.unmatched:
123
+ print(f" Missing : {', '.join(r.unmatched)}")
124
+ if r.matched:
125
+ print(f" Covered : {', '.join(r.matched)}")
126
+ print(f" Tools : {', '.join(r.generated_tools)}")
127
+ print(f"\n{SEP}")
128
+ avg = sum(r.overall_score for r in results) / len(results) if results else 0
129
+ passing = sum(1 for r in results if r.overall_score >= 0.7)
130
+ print(f" Result : {passing}/{len(results)} passing Average score : {avg:.0%}")
131
+ print(SEP)
@@ -0,0 +1,26 @@
1
+ from pydantic_settings import BaseSettings
2
+
3
+
4
+ class Settings(BaseSettings):
5
+ """LLM provider settings, read from the environment or a local .env file.
6
+
7
+ Set any one key. When several are set they are tried in this order,
8
+ falling through to the next on quota or server errors:
9
+ Anthropic, OpenAI, Gemini.
10
+ """
11
+
12
+ anthropic_api_key: str = ""
13
+ anthropic_model: str = "claude-opus-5-5"
14
+
15
+ openai_api_key: str = ""
16
+ openai_model: str = "gpt-4o-mini"
17
+
18
+ gemini_api_key: str = ""
19
+ gemini_model: str = "gemini-2.5-flash"
20
+ # Comma-separated extra Gemini models tried on the same key when the primary hits its quota
21
+ gemini_fallback_models: str = ""
22
+
23
+ model_config = {"env_file": ".env", "env_file_encoding": "utf-8", "extra": "ignore"}
24
+
25
+
26
+ settings = Settings()
File without changes
@@ -0,0 +1,60 @@
1
+ """Typed errors for the discovery and condensation pipeline."""
2
+ from __future__ import annotations
3
+
4
+
5
+ class DiscoveryError(Exception):
6
+ """Base class for all pipeline errors."""
7
+
8
+
9
+ class SpecNetworkError(DiscoveryError):
10
+ """Target host is unreachable."""
11
+
12
+
13
+ class SpecParseError(DiscoveryError):
14
+ """Found a spec-like file but could not parse it."""
15
+ def __init__(self, path: str):
16
+ self.spec_path = path
17
+ super().__init__(f"Could not parse spec at {path}")
18
+
19
+
20
+ class SpecEmptyError(DiscoveryError):
21
+ """Spec parsed successfully but contained no endpoints."""
22
+ def __init__(self, path: str = ""):
23
+ self.spec_path = path
24
+ super().__init__(f"Spec at {path} has no parseable endpoints")
25
+
26
+
27
+ class PlaywrightNotInstalledError(DiscoveryError):
28
+ """Playwright is not installed."""
29
+
30
+
31
+ class TrafficNetworkError(DiscoveryError):
32
+ """Could not load the target page."""
33
+
34
+
35
+ class NoXHRCapturedError(DiscoveryError):
36
+ """Page loaded but made no XHR/fetch calls (server-rendered)."""
37
+
38
+
39
+ class AllTrackersFilteredError(DiscoveryError):
40
+ """XHR calls seen but all matched the tracker blocklist."""
41
+
42
+
43
+ class BrandFilteredError(DiscoveryError):
44
+ """XHR calls seen but none matched the service brand."""
45
+ def __init__(self, base_brand: str, seen_brands: list[str]):
46
+ self.base_brand = base_brand
47
+ self.seen_brands = seen_brands
48
+ super().__init__(f"No XHR calls matched brand '{base_brand}'")
49
+
50
+
51
+ class LLMQuotaError(DiscoveryError):
52
+ """All AI providers exhausted their quota."""
53
+
54
+
55
+ class LLMInvalidResponseError(DiscoveryError):
56
+ """AI returned a response that could not be parsed as valid JSON."""
57
+
58
+
59
+ class LLMEmptySchemaError(DiscoveryError):
60
+ """AI returned valid JSON but with no tools."""