{"id":49002676,"url":"https://github.com/elgrhy/gx","last_synced_at":"2026-05-31T07:00:46.822Z","repository":{"id":352264427,"uuid":"1028134250","full_name":"elgrhy/gx","owner":"elgrhy","description":"Brain-first programming language for building transparent, auditable AI assistants. Write AI agents as simply as a recipe. Non-hallucinating, zero cloud lock-in.","archived":false,"fork":false,"pushed_at":"2026-05-29T11:07:11.000Z","size":1359,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T13:06:32.046Z","etag":null,"topics":["ai","ai-agents","anthropic","brain-first","interpreter","llm","ollama","openai","programming-language","rust"],"latest_commit_sha":null,"homepage":"https://github.com/elgrhy/gx","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/elgrhy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-29T04:56:43.000Z","updated_at":"2026-05-29T11:07:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/elgrhy/gx","commit_stats":null,"previous_names":["elgrhy/gx"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/elgrhy/gx","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elgrhy%2Fgx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elgrhy%2Fgx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elgrhy%2Fgx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elgrhy%2Fgx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/elgrhy","download_url":"https://codeload.github.com/elgrhy/gx/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/elgrhy%2Fgx/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33722156,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","anthropic","brain-first","interpreter","llm","ollama","openai","programming-language","rust"],"created_at":"2026-04-18T19:04:12.166Z","updated_at":"2026-05-31T07:00:46.816Z","avatar_url":"https://github.com/elgrhy.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GX Language\n\n**Brain-first programming language for building transparent, auditable AI assistants.**\n\nEvery AI assistant today is a black box. GX makes it a glass box — every decision explicit, every AI call logged, every agent fully debuggable. Built in Rust. Runs anywhere. No cloud lock-in.\n\n[![Crates.io](https://img.shields.io/crates/v/gxlang)](https://crates.io/crates/gxlang)\n[![npm](https://img.shields.io/npm/v/gxlang)](https://www.npmjs.com/package/gxlang)\n[![CI](https://github.com/elgrhy/gx/actions/workflows/ci.yml/badge.svg)](https://github.com/elgrhy/gx/actions)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n---\n\n## Install\n\n```bash\n# macOS / Linux — one-line installer\ncurl -sSf https://raw.githubusercontent.com/elgrhy/gx/main/install.sh | sh\n\n# npm (any platform with Node.js 16+)\nnpm install -g gxlang\n\n# Cargo\ncargo install gxlang\n\n# From source\ngit clone https://github.com/elgrhy/gx.git \u0026\u0026 cd gx \u0026\u0026 cargo build --release\n```\n\n```bash\ngx --version   # gx 0.4.0\n```\n\n---\n\n## Quick Start\n\n```bash\ngx init my-agent\ncd my-agent\ngx run main.gx\n```\n\n```gx\nagent \"hello\" {\n  when started {\n    name = \"World\"\n    say \"Hello, {name}! GX v0.4.0 is running.\"\n  }\n}\n```\n\n---\n\n## What's New in v0.4.0\n\nThe biggest release yet — GX now competes with Python for agent-building.\n\n### Regex — Full Pattern Matching\n\n```gx\nprice  = regex_find(\"Total: $42.50\", \"\\\\$([0-9.]+)\")       // \"42.50\"\nscores = regex_find_all(\"85, 92, 100\", \"\\\\d+\")              // [\"85\",\"92\",\"100\"]\nvalid  = regex_test(email, \"@\")\nclean  = regex_replace(\"hello   world\", \"\\\\s+\", \" \")\nparts  = regex_split(\"a::b::c\", \":+\")                       // [\"a\",\"b\",\"c\"]\ncaps   = regex_captures(\"2024-01-15\", \"(\\\\d{{4}})-(\\\\d{{2}})-(\\\\d{{2}})\")\n// caps[1]=\"2024\", caps[2]=\"01\", caps[3]=\"15\"\n```\n\n### Date / Time\n\n```gx\nnow   = date_now()                          // \"2025-05-30T14:23:01Z\"\nts    = date_parse(\"2024-01-15\")            // Unix timestamp\nts2   = date_parse(\"Jan 15, 2024\")          // auto-detects format\nfmt   = date_format(ts, \"%B %d, %Y\")        // \"January 15, 2024\"\ndiff  = date_diff(ts, date_now(), \"days\")\nnext  = date_add(ts, 7, \"days\")\nparts = date_parts(ts)  // { year, month, day, hour, minute, second, weekday }\n```\n\n### CSV, YAML, TOML\n\n```gx\nrows   = csv_parse(read_file(\"data.csv\"))        // auto-types numbers \u0026 booleans\nout    = csv_stringify(rows)\n\nconfig = yaml_parse(read_file(\"config.yml\"))\nyaml_out = yaml_stringify(config)\n\nmanifest = toml_parse(read_file(\"Cargo.toml\"))\nlog(manifest.package.version)                    // \"0.4.0\"\n```\n\n### .env File Loading\n\n```gx\nload_env(\".env\")                              // loads KEY=VALUE, never overwrites existing\nkey = get_env(\"OPENAI_API_KEY\", \"\")           // second arg is default\nurl = get_env(\"API_URL\", \"https://localhost\")\n```\n\n### Language Bridges — TypeScript, Go, Any Binary\n\n```gx\n// TypeScript — auto-detects tsx or ts-node\nuse ts.analytics\nresult = ts.analytics.process(events)\n\n// Go / Rust / Java / .NET — JSON stdin/stdout protocol\nuse binary \"./my_rust_service\"\noutput = binary.transform(payload)\n\nuse go \"./analytics_server\"\nstats = go.compute(events)\n\n// Python (unchanged)\nuse py.pandas\ndf = py.pandas.read_csv(\"data.csv\")\n```\n\n### AI Tool Use — Function Calling\n\n```gx\ntool \"search_web\" {\n  description: \"Search the web for current information\"\n  params: {\n    query: { type: \"string\", required: true }\n  }\n  execute(query) {\n    result = http_get(\"https://api.search.example.com?q={query}\")\n    return result.data\n  }\n}\n\nagent \"researcher\" {\n  when started {\n    response = ask openai {\n      prompt: \"What is the current Bitcoin price?\",\n      tools:  [search_web],\n      model:  \"gpt-4o\"\n    }\n    if response.tool_calls != null {\n      for each call in response.tool_calls {\n        log(\"AI called: \" + call.name + \" with \" + json_stringify(call.arguments))\n      }\n    }\n    say response.text\n  }\n}\n```\n\n### Streaming AI\n\n```gx\nresult = ask openai {\n  prompt: \"Write a 500-word essay on AI transparency\",\n  stream: true    // chunks print in real-time; result.text has the full assembled text\n}\n```\n\n### Persistent Memory — Survives Restarts\n\n```gx\nagent \"counter\" {\n  remember { count = 0 }\n\n  when started {\n    load_memory()          // loads from ~/.gx/state/counter.db (SQLite)\n    memory.count += 1\n    log(\"Run #{memory.count}\")\n    persist_memory()       // saves back to SQLite\n  }\n}\n```\n\n### Vector Store — Semantic Search\n\n```gx\nstore = vector_store_new(\"docs\")\nvector_store_add(store, \"doc1\", embed(\"The cat sat on the mat\"), \"cat story\")\nvector_store_add(store, \"doc2\", embed(\"Dogs are loyal companions\"),  \"dog story\")\n\nhits = vector_store_search(store, embed(\"feline pets\"), 3)\nlog(hits[0].label)   // \"cat story\"\nlog(hits[0].score)   // cosine similarity score\n\nsim = cosine_similarity([1.0, 0.0], [0.7, 0.7])\n```\n\n### Schema Validation\n\n```gx\nspec = { name: \"string\", age: \"number\", email: { type: \"string\", required: false } }\nr = schema_validate(user_input, spec)\nif !r.ok {\n  for each err in r.errors { log(\"Error: \" + err) }\n}\n```\n\n### Await Block — Concurrent I/O\n\n```gx\nawait {\n  weather: http_get(\"https://api.weather.com/london\"),\n  news:    http_get(\"https://api.news.com/top\"),\n  stocks:  http_get(\"https://api.stocks.com/AAPL\")\n} into data\n\nlog(data.weather.body)\n```\n\n### Retry with Backoff\n\n```gx\nresult = retry(fn() {\n  return ask openai { prompt: \"Classify this text\" }\n}, 5, { delay: 1000, backoff: \"exponential\" })\n// Retries up to 5×: 1s, 2s, 4s, 8s, 16s — capped at 30s\n```\n\n### Observability — Structured JSONL Tracing\n\n```gx\ntrace_log(\"pipeline.start\", { query: memory.query })\nresult = ask anthropic { prompt: memory.query }\ntrace_log(\"ai.done\", { tokens: result.tokens_used })\n// Emits: {\"ts\":1748609381000,\"agent\":\"my_agent\",\"event\":\"ai.done\",\"data\":{...}} to stderr\n```\n\n---\n\n## Core Language\n\n### Agent Structure\n\n```gx\nagent \"my_agent\" {\n  goal: \"Do something useful\"\n  retry: 3\n  timeout: 30s\n  on_error: escalate\n\n  remember {\n    count = 0\n    items = []\n  }\n\n  when started {\n    memory.count += 1\n    say \"Run #{memory.count}\"\n  }\n\n  when memory.count \u003e 100 {\n    memory.count = 0\n    log(\"Reset counter\")\n  }\n\n  when cron \"0 9 * * 1-5\" {\n    log(\"Good morning, it's a weekday\")\n  }\n}\n```\n\n### Functions — Three Scopes\n\n```gx\n// 1. File-root — available to all agents\nfunction format_price(amount) {\n  return \"$\" + to_string(round(amount * 100) / 100)\n}\n\nagent \"shop\" {\n  // 2. Agent-level — available across all when blocks\n  function validate_order(order) {\n    return schema_validate(order, { item: \"string\", qty: \"number\" })\n  }\n\n  when started {\n    // 3. Inline — scoped to this block\n    function greet(name) { return \"Hello, {name}!\" }\n    log(greet(\"Alice\"))\n  }\n}\n```\n\n### Module System\n\n```gx\nimport \"utils/math.gx\"    as math\nimport \"utils/strings.gx\" as str\n\nresult = math.add(10, 32)         // 42\nlabel  = str.truncate(result, 5)  // \"42...\"\n```\n\n### Range Slicing\n\n```gx\ns = \"hello world\"\ns[0..5]    // \"hello\"\ns[6..11]   // \"world\"\n\narr = [1, 2, 3, 4, 5]\narr[1..4]  // [2, 3, 4]\n```\n\n### String Interpolation\n\n```gx\nname = \"GX\"\n\"Hello from {name}!\"          // \"Hello from GX!\"\n\"Literal brace: {{name}}\"     // \"Literal brace: {name}\"\n\"Result: {1 + 2 * 3}\"         // \"Result: 7\"\n```\n\n### Control Flow\n\n```gx\n// Range for loop\nfor n in range(1, 11) { log(n) }\n\n// While with break/continue\nwhile running {\n  line = readline()\n  if line == null { break }\n  if line.starts_with(\"#\") { continue }\n  process(line)\n}\n\n// Try/catch with typed errors\ntry {\n  result = http_post(url, payload)\n} catch NetworkError e {\n  log(\"Network: \" + e)\n} catch e {\n  log(\"Other: \" + e)\n}\n\n// Await — concurrent branches\nawait { a: expr1, b: expr2, c: expr3 } into results\n\n// Retry with backoff\nresult = retry(fn() { risky_call() }, 3, { backoff: \"exponential\" })\n```\n\n---\n\n## Built-in Reference\n\n| Category | Builtins |\n|----------|---------|\n| **AI** | `ask openai/anthropic/ollama` (streaming + tool use), `embed`, `infer classifier` |\n| **HTTP** | `http_get`, `http_post`, `http_put`, `http_delete`, `http_stream`, `http_upload` |\n| **File I/O** | `read_file`, `write_file`, `delete_file`, `file_exists`, `list_dir`, `make_dir` |\n| **JSON** | `json_stringify` (integers stay integers), `json_parse` |\n| **CSV** | `csv_parse` (auto-types), `csv_stringify` |\n| **YAML** | `yaml_parse`, `yaml_stringify` |\n| **TOML** | `toml_parse`, `toml_stringify` |\n| **Regex** | `regex_test`, `regex_find`, `regex_find_all`, `regex_replace`, `regex_split`, `regex_captures`, `regex_named_captures` |\n| **Date** | `date_now`, `date_timestamp`, `date_parse`, `date_format`, `date_diff`, `date_add`, `date_parts`, `date_from_parts` |\n| **Math** | `abs`, `floor`, `ceil`, `round`, `sqrt`, `pow`, `min(a,b,…)`, `max(a,b,…)`, `random` |\n| **String** | `.trim()`, `.upper()`, `.lower()`, `.contains()`, `.replace()`, `.split()`, `.reverse()`, `.slice()`, `.starts_with()`, `.ends_with()`, `.len()`, `.repeat()`, `.pad_left()`, `.pad_right()` |\n| **Array** | `.sort()`, `.filter_by()`, `.unique()`, `.flatten()`, `.sum()`, `.min()`, `.max()`, `.average()`, `.take()`, `.skip()`, `.map_field()` |\n| **DB** | `db_query`, `db_exec` (SQLite, bundled) |\n| **Env** | `load_env`, `get_env(key, default)`, `set_env` |\n| **Shell** | `shell()` (requires `--allow-shell`) |\n| **Vector** | `vector_store_new`, `vector_store_add`, `vector_store_search`, `vector_store_delete`, `vector_store_size`, `cosine_similarity` |\n| **Schema** | `schema_validate(value, spec)` |\n| **Memory** | `persist_memory()`, `load_memory()` |\n| **Base64** | `base64_encode`, `base64_decode` |\n| **I/O** | `readline()`, `read_all()` |\n| **Observability** | `trace_log(event, data)` |\n| **Retry** | `retry(fn, max, opts)` |\n| **Slice/Merge** | `slice(arr_or_str, start, end)`, `merge(obj1, obj2, …)` |\n| **Type** | `type_of`, `is_null`, `to_string`, `to_number`, `len` |\n\n---\n\n## Language Interop\n\n| Language | Syntax | How it works |\n|----------|--------|-------------|\n| JavaScript | `use js.axios` | Persistent Node.js subprocess, JSON IPC |\n| TypeScript | `use ts.mylib` | Auto-detects `tsx` or `ts-node` |\n| Python | `use py.requests` | Persistent Python subprocess, JSON IPC |\n| Go | `use go \"./service\"` | Compiled binary, JSON stdin/stdout |\n| Any binary | `use binary \"./app\"` | Same JSON protocol — Rust, Java, .NET, C++ |\n\n---\n\n## Progressive Syntax\n\nThree levels that compile to the same runtime — pick the verbosity you want:\n\n```gx\n// Level 1 — Pure intent\nAgent greeter\nname = \"World\"\n\"Hello {name}\"\n\n// Level 2 — Named behaviors\nAgent assistant\nOn start:\n  Greet\n\nGreet:\n  say \"Hello!\"\n\n// Level 3 — Explicit brain cycle\nAgent processor\nPlan:\n  action = \"process\"\nExecute:\n  If action == \"process\"\n    result = transform(input)\nRemember:\n  memory.last = result\nCommunicate:\n  result\n```\n\n---\n\n## AI Providers\n\n| Provider | Env Variable | Default Model |\n|----------|-------------|---------------|\n| OpenAI | `OPENAI_API_KEY` | `gpt-4o-mini` |\n| Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-6` |\n| Ollama (local) | `OLLAMA_URL` (default `localhost:11434`) | `llama3` |\n\n---\n\n## Security Model\n\nGX is secure by default — all dangerous operations require explicit opt-in:\n\n| Operation | Default | Flag to enable |\n|-----------|---------|----------------|\n| Shell execution | Blocked | `--allow-shell` |\n| Internal HTTP (SSRF) | Blocked | `--allow-internal-http` |\n| File access | Sandboxed to script dir | `--no-sandbox` |\n\n---\n\n## Toolchain\n\n```bash\ngx run main.gx              # Run a GX program\ngx check main.gx            # Syntax check (no execution)\ngx init my-project          # Scaffold a new project\ngx test                     # Run all *.test.gx files\ngx fmt main.gx              # Format source\ngx build                    # Compile for distribution\ngx install js.axios         # Add JS dependency\ngx install py.requests      # Add Python dependency\n```\n\n---\n\n## Version History\n\n| Version | Highlights |\n|---------|-----------|\n| **v0.4.2** | **Source-located runtime errors** — every runtime error now reports `at line N` plus a call-stack trace (`in agent \"x\" → fn() → \u003cclosure\u003e`). Published to crates.io as `gxlang` (binary stays `gx`). |\n| **v0.4.1** | **Real closures** — lambdas capture enclosing locals (unblocks `retry()`, `map`/`filter`, functional composition) · `obj.field(args)` calls a stored closure (dispatch tables) · **Top-level statements** — `x = 1`, `load_env(\".env\")` at file root · `is_tty()` builtin + non-blocking `read_all()` on TTY · `--no-limit` flag + raised loop cap (10M) with wall-clock timeout removed · Test builtins `assert_eq`/`assert_true`/`assert_contains` · `gx test` single-file + `test_*.gx`/`*.test.gx` discovery · \"Did you mean?\" suggestions + clearer division-by-zero errors |\n| **v0.4.0** | Regex · Date/Time · CSV/YAML/TOML · TypeScript+Go+Binary bridges · AI tool use · Streaming AI · Persistent memory (SQLite) · Vector store · Schema validation · `await {}` concurrent block · Retry with backoff · Observability tracing · `string.reverse()` · Vararg `min()`/`max()` · Memory-propagating function calls |\n| **v0.3.0** | Security audit · Sandbox \u0026 SSRF protection · Shell gate · Module system (`import … as alias`) · `!` operator · Integer JSON · Range slicing `[a..b]` · `output` unreserved · Standalone `slice()`/`merge()` · `readline()` |\n| **v0.2.5** | HTTPS/TLS fix · Shell stdin · Quoted object keys |\n| **v0.2.0** | `think`/`act`/`observe` · `parallel {}` · `retry:` · Multi-agent orchestration |\n| **v0.1.0** | Initial release — lexer, parser, interpreter, OpenAI/Anthropic/Ollama |\n\n---\n\n## Contributing\n\n```bash\ncargo test                       # 72 unit tests — must all pass\ngx run tests/test_v04_full.gx    # 678 integration checks\ncargo clippy -- -D warnings      # zero warnings\ncargo fmt --check                # formatted\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for details.\n\n---\n\n## License\n\nMIT — © 2025 Ahmed Elgarhy / DEVJSX LIMITED (London, UK). Company No: 16618207.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felgrhy%2Fgx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Felgrhy%2Fgx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Felgrhy%2Fgx/lists"}