Skip to content

Commit 30e13a2

Browse files
author
andrey.korchemkin
committed
chore(init): initialize project structure with core files and directories
Add initial setup including documentation, build files, source code directories, and configuration for a Go project. Includes license, contributing guidelines, and CI/CD setup via .github/. This establishes the foundational repository structure.
0 parents  commit 30e13a2

106 files changed

Lines changed: 340582 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.editorconfig‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
root = true
2+
3+
[*]
4+
charset = utf-8
5+
end_of_line = lf
6+
insert_final_newline = true
7+
indent_style = space
8+
indent_size = 4
9+
trim_trailing_whitespace = true
10+
11+
[*.go]
12+
indent_style = tab
13+
indent_size = 4
14+
15+
[Makefile]
16+
indent_style = tab
17+
18+
[*.md]
19+
trim_trailing_whitespace = false
20+
21+
[*.ps1]
22+
end_of_line = crlf
23+
indent_style = space
24+
indent_size = 4

‎.gitattributes‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
* text=auto
2+
*.go text eol=lf
3+
*.md text eol=lf
4+
*.yaml text eol=lf
5+
*.yml text eol=lf
6+
*.json text eol=lf
7+
Makefile text eol=lf
8+
*.ps1 text eol=crlf

‎.github/workflows/ci.yml‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
name: ci
2+
3+
on:
4+
push:
5+
branches:
6+
- "**"
7+
pull_request:
8+
9+
jobs:
10+
windows:
11+
runs-on: windows-latest
12+
steps:
13+
- uses: actions/checkout@v4
14+
15+
- uses: actions/setup-go@v5
16+
with:
17+
go-version-file: go.mod
18+
19+
- name: Bootstrap
20+
shell: pwsh
21+
run: ./scripts/bootstrap.ps1
22+
23+
- name: Format
24+
shell: pwsh
25+
run: ./scripts/format.ps1
26+
27+
- name: Verify Formatting
28+
shell: pwsh
29+
run: git diff --exit-code
30+
31+
- name: Lint
32+
shell: pwsh
33+
run: ./scripts/lint.ps1
34+
35+
- name: Test
36+
shell: pwsh
37+
run: ./scripts/test.ps1
38+
39+
- name: Build
40+
shell: pwsh
41+
run: ./scripts/build.ps1
42+
43+
- name: Example Smoke
44+
shell: pwsh
45+
run: ./scripts/run-example.ps1
46+
47+
ubuntu:
48+
runs-on: ubuntu-latest
49+
steps:
50+
- uses: actions/checkout@v4
51+
52+
- uses: actions/setup-go@v5
53+
with:
54+
go-version-file: go.mod
55+
56+
- name: Download Modules
57+
run: go mod download
58+
59+
- name: Format
60+
run: go fmt ./...
61+
62+
- name: Verify Formatting
63+
run: git diff --exit-code
64+
65+
- name: Vet
66+
run: go vet ./...
67+
68+
- name: Test
69+
run: go test ./...
70+
71+
- name: Build
72+
run: mkdir -p dist && go build -trimpath -o dist/toolc ./cmd/toolc
73+
74+
- name: Example Smoke
75+
run: |
76+
./dist/toolc compile -importer openapi -source testdata/fixtures/openapi.todo.yaml -out dist/openapi.compiled.json
77+
./dist/toolc inspect -importer function -source testdata/fixtures/synthetic.functions.json -stage compile

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
dist/
2+
coverage.out
3+
*.test
4+
*.exe
5+
*.dll
6+
*.so
7+
*.dylib
8+
*.out
9+
.vscode/
10+
.idea/
11+
.codex/
12+
.tmp/
13+
Thumbs.db
14+
Desktop.ini

‎AGENTS.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# AGENTS.md
2+
3+
## Purpose
4+
5+
This repository builds `toolc`: a Tool Catalog Compiler + Gateway centered on a single IR and a pass-based compiler.
6+
7+
## Working Rules
8+
9+
- Keep Windows 11 + PowerShell as the primary contributor workflow.
10+
- Do not make Bash-only tooling mandatory.
11+
- Prefer standard library solutions unless a real requirement justifies another dependency.
12+
- Keep the IR in `internal/ir` as the system of record.
13+
- Importers must translate provider-native inputs into IR before compiler logic runs.
14+
- Compiler behavior should remain deterministic and testable.
15+
- Gateway changes should keep startup/build/test loops fast and local.
16+
- Benchmark code belongs in `internal/bench`, not mixed into runtime paths.
17+
18+
## Validation Loop
19+
20+
Before considering work complete, run:
21+
22+
```powershell
23+
./scripts/check.ps1
24+
```
25+
26+
If only a subset changed, at minimum run the affected package tests plus:
27+
28+
```powershell
29+
./scripts/build.ps1
30+
```
31+
32+
## Current MVP Boundaries
33+
34+
- `function` importer works for raw YAML/JSON tool lists and catalog-like inputs
35+
- `openapi` importer covers a practical OAS3 subset, not the full spec
36+
- `mcp` importer currently consumes MCP-like manifests/tool metadata, not live wire sessions
37+
- gateway supports discovery/schema/invoke HTTP flows, but invocation is still backed by a mock adapter
38+
- model config is loaded now for later OpenAI-compatible execution work
39+
40+
## Change Guidance
41+
42+
- Preserve honest documentation. Do not imply provider/runtime support that does not exist.
43+
- Prefer adding tests with new compiler/importer behavior.
44+
- Keep scripts reproducible and CI-friendly.
45+
- Update `docs/architecture.md` when changing architectural boundaries.

‎BENCHMARK_REPORT.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Benchmark Report
2+
3+
- Suite: `release`
4+
- Started: `2026-04-11 20:43:07 MSK`
5+
- Finished: `2026-04-11 20:48:13 MSK`
6+
- Environment: `windows/amd64`
7+
- Model evaluation: enabled (`z-ai/glm-5.1` via `https://openrouter.ai/api/v1`)
8+
9+
Task success rate in this report means: correct tool selection + schema-valid arguments + local task oracle assertions. It is not a claim of end-to-end external API execution success.
10+
11+
## Scenario Summary
12+
13+
| Scenario | Layer | Tools | Namespaces | Compile | Index | Namespace | Schema | Invoke |
14+
| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
15+
| synthetic-10 | synthetic | 10 | 10 | 517.000 us | 5.144 us | 5.174 us | 0 | 0 |
16+
| synthetic-50 | synthetic | 50 | 10 | 2.250 ms | 29.942 us | 0 | 0 | 0 |
17+
| synthetic-200 | synthetic | 200 | 10 | 6.433 ms | 89.988 us | 5.766 us | 0 | 0 |
18+
| synthetic-500 | synthetic | 500 | 10 | 15.539 ms | 145.770 us | 0 | 8.842 us | 7.331 us |
19+
| bfcl-live-simple-subset | real-world | 4 | 1 | 0 | 4.630 us | 0 | 0 | 0 |
20+
| github-collaboration-subset | real-world | 14 | 2 | 4.570 ms | 9.985 us | 0 | 65.863 us | 0 |
21+
| github-rest-full-metrics | real-world | 1112 | 44 | 118.652 ms | 218.875 us | 9.994 us | 0 | 0 |
22+
23+
## synthetic-10
24+
25+
Small synthetic catalog with model evaluation enabled.
26+
27+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
28+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
29+
| raw | 10.0 | 910.0 | 0.00 | 0.00 | 1.00 | 1.259 s | 1.259 s |
30+
| baseline | 2.3 | 246.3 | 0.00 | 0.00 | 1.00 | 750.658 ms | 750.658 ms |
31+
| compiled | 10.0 | 448.0 | 0.00 | 0.00 | 1.00 | 662.831 ms | 662.831 ms |
32+
33+
34+
## synthetic-50
35+
36+
Medium synthetic catalog for structural metrics only in the release run.
37+
38+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
39+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
40+
| raw | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
41+
42+
Skipped reason for `raw`: model evaluation disabled for scenario
43+
44+
| baseline | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
45+
46+
Skipped reason for `baseline`: model evaluation disabled for scenario
47+
48+
| compiled | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
49+
50+
Skipped reason for `compiled`: model evaluation disabled for scenario
51+
52+
53+
54+
## synthetic-200
55+
56+
Large synthetic catalog for structural metrics only in the release run.
57+
58+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
59+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
60+
| raw | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
61+
62+
Skipped reason for `raw`: model evaluation disabled for scenario
63+
64+
| baseline | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
65+
66+
Skipped reason for `baseline`: model evaluation disabled for scenario
67+
68+
| compiled | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
69+
70+
Skipped reason for `compiled`: model evaluation disabled for scenario
71+
72+
73+
74+
## synthetic-500
75+
76+
Very large synthetic catalog for structural metrics only in the release run.
77+
78+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
79+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
80+
| raw | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
81+
82+
Skipped reason for `raw`: model evaluation disabled for scenario
83+
84+
| baseline | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
85+
86+
Skipped reason for `baseline`: model evaluation disabled for scenario
87+
88+
| compiled | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
89+
90+
Skipped reason for `compiled`: model evaluation disabled for scenario
91+
92+
93+
94+
## bfcl-live-simple-subset
95+
96+
BFCL subset with model evaluation enabled for a bounded set of tasks.
97+
98+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
99+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
100+
| raw | 4.0 | 742.0 | 0.00 | 0.00 | 1.00 | 3.203 s | 3.203 s |
101+
| baseline | 1.8 | 362.8 | 0.00 | 0.00 | 1.00 | 921.339 ms | 921.339 ms |
102+
| compiled | 4.0 | 188.0 | 0.25 | 0.50 | 0.25 | 3.182 s | 10.067 s |
103+
104+
105+
## github-collaboration-subset
106+
107+
Official GitHub REST API subset with model evaluation enabled for a bounded set of tasks.
108+
109+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
110+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
111+
| raw | 14.0 | 6322.0 | 0.25 | 0.50 | 0.00 | 4.949 s | 0 |
112+
| baseline | 5.0 | 2576.8 | 0.25 | 0.25 | 0.25 | 3.062 s | 1.227 s |
113+
| compiled | 14.0 | 360.0 | 0.50 | 0.50 | 0.50 | 3.005 s | 4.482 s |
114+
115+
116+
## github-rest-full-metrics
117+
118+
Full official GitHub REST API description for import/compile/gateway metrics only.
119+
120+
| Variant | Avg visible tools | Avg token proxy | Wrong-tool rate | Invalid-args rate | Task success rate | Avg latency | Useful selection |
121+
| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
122+
| raw | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
123+
124+
Skipped reason for `raw`: scenario has no tasks
125+
126+
| baseline | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
127+
128+
Skipped reason for `baseline`: scenario has no tasks
129+
130+
| compiled | 0.0 | 0.0 | 0.00 | 0.00 | 0.00 | 0 | 0 |
131+
132+
Skipped reason for `compiled`: scenario has no tasks
133+
134+
135+
Notes:
136+
- scenario contains no task oracle; only structural metrics, compile time, and gateway overhead were measured
137+
138+

‎CHANGELOG.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Changelog
2+
3+
All notable changes to this repository will be documented in this file.
4+
5+
The project is pre-1.0, so changes may still reshape APIs and behavior. The goal of this changelog is clarity, not semantic-versioning theater.
6+
7+
## Unreleased
8+
9+
### Added
10+
11+
- unified IR for tool catalogs with namespaces, safety flags, provenance, examples, and hot/deferred metadata
12+
- importers for raw function catalogs, OpenAPI specs, and MCP-like manifests
13+
- deterministic compiler pipeline with golden regression tests
14+
- runtime gateway with profiles, policy controls, trace IDs, and dry-run invocation
15+
- mock execution backend behind a production-shaped adapter boundary
16+
- Windows-first helper scripts for bootstrap, format, lint, test, build, and example runs
17+
- benchmark microtests for compiler and gateway hot paths
18+
- CI for formatting, linting, tests, builds, and example smoke checks
19+
- public-facing documentation set for architecture, IR, gateway behavior, benchmarking, Windows setup, and demo flow

0 commit comments

Comments
 (0)