{"id":49026787,"url":"https://github.com/shuuida/jutsu-lang","last_synced_at":"2026-04-19T07:01:56.664Z","repository":{"id":349877281,"uuid":"1204320540","full_name":"Shuuida/jutsu-lang","owner":"Shuuida","description":"Jutsu is an experimental, domain-specific programming language pioneering the Inference-Oriented Programming (IOP) paradigm. While traditional languages model deterministic states, Jutsu is engineered from the ground up to natively orchestrate asynchronous swarms of Artificial Intelligence agents safely and concurrently at the local hardware level.","archived":false,"fork":false,"pushed_at":"2026-04-07T23:58:02.000Z","size":66,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T01:08:11.631Z","etag":null,"topics":["ai-agents","concurrency","dsl","edge-ai","ffi","gguf","interpreter","llamacpp","llm","local-ai","orchestration","programming-language","rust","tokio"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Shuuida.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2026-04-07T22:44:50.000Z","updated_at":"2026-04-07T23:58:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Shuuida/jutsu-lang","commit_stats":null,"previous_names":["shuuida/jutsu-lang"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Shuuida/jutsu-lang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuuida%2Fjutsu-lang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuuida%2Fjutsu-lang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuuida%2Fjutsu-lang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuuida%2Fjutsu-lang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Shuuida","download_url":"https://codeload.github.com/Shuuida/jutsu-lang/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Shuuida%2Fjutsu-lang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31997804,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"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-agents","concurrency","dsl","edge-ai","ffi","gguf","interpreter","llamacpp","llm","local-ai","orchestration","programming-language","rust","tokio"],"created_at":"2026-04-19T07:01:55.435Z","updated_at":"2026-04-19T07:01:56.655Z","avatar_url":"https://github.com/Shuuida.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tengen Engine | Jutsu Programming Language\n\n![Version](https://img.shields.io/badge/version-v0.2.0--alpha-orange)\n![License](https://img.shields.io/badge/license-MIT%20%2F%20OpenSource-blue)\n![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey)\n![Backend](https://img.shields.io/badge/backend-Rust%20%2B%20llama.cpp-red)\n\n\u003e ⚠️ **PROJECT STATUS: v0.2.0-alpha**\n\u003e Jutsu is an experimental language in an early alpha phase. The inference engine (Tengen Engine) is strictly tied to the local hardware architecture. Dynamic typing, parser syntax, and standard primitives are subject to change without prior notice (Breaking Changes) in future versions.\n\nJutsu is a domain-specific programming language designed for **Inference-Oriented Programming (IOP)**. It does not compile traditional software; it orchestrates asynchronous swarms of Artificial Intelligence Agents natively, concurrently, and safely at the local hardware level.\n\n---\n\n## 🧠 The Philosophy: Inference-Oriented Programming (IOP)\n\nFor decades, **Object-Oriented Programming (OOP)** modeled the world through deterministic states and encapsulated behaviors. In the era of generative AI, that structured paradigm is somewhat complicated to handle given the probabilistic nature of language models when it comes to inference and not just training.\n\nJutsu introduces **Inference-Oriented Programming (IOP)**. In Jutsu, the fundamental unit is not an \"Object\", but a **Vessel**: a cognitive node loaded with local mathematical weights (Tensors). \nInstead of calling methods with predictable results, in IOP you manage *Contexts*, define *restrictive Grammars* (GBNF), and route flows of \"thought\" through asynchronous workers (`workers`). Jutsu delegates business logic to the natural language of the AI and reserves hard code for strict hardware orchestration, memory queues, and system calls (Skill Calling).\n\n---\n\n## ⚙️ Backend Architecture (Tengen Engine)\n\nThe brain behind Jutsu is the **Tengen Engine**. Its architecture is divided into three critical layers that guarantee industrial-grade concurrency:\n\n1. **The Language Frontend (Rust):** Uses `logos` for lightning-fast lexical analysis and a hand-written *Pratt Parser* (Top-Down Operator Precedence Parser). It generates a dynamic Abstract Syntax Tree (AST) capable of evaluating variables recursively.\n2. **The Asynchronous Engine (Tokio):** The entire execution environment (Runtime) runs on a Tokio Event Loop. Multiple `worker` blocks generate background threads (Shadow Workers) that operate in parallel without blocking the operating system's main thread.\n3. **The Hardware Bridge (FFI + llama.cpp):** Tengen Engine links directly with the C/C++ backend of `llama.cpp`. It uses an **Asynchronous Hardware Mutex (`Arc\u003cAsyncMutex\u003c()\u003e\u003e`)** system. This ensures that thousands of threads can share a global task queue in RAM, but only one thread at a time accesses the graphics card's VRAM, eliminating Out-Of-Memory (OOM) crashes and context corruption (KV-Cache).\n\n---\n\n## 🚀 Installation and Deployment\n\nJutsu is designed for both rapid deployments and deep engine development.\n\n### Option A: Installation from Binaries (Recommended)\n1. Download the `.zip` file of the latest version from the **Releases** tab of this repository.\n2. Extract the content (which includes `tgn.exe` and the base hardware `.dll`s that you can swap out for the ones you download, as long as they are from the exact same b8115 build that Jutsu uses) into a directory, for example: `C:\\Jutsu`.\n3. Add `C:\\Jutsu` to your operating system's `PATH` environment variable.\n4. Open your terminal and type `tgn --version`.\n\n### Option B: Clone and Compile (Developer Mode)\n**Dependencies:** Requires the [Rust and Cargo](https://rustup.rs/) compiler installed on your machine.\n```bash\n# 1. Clone the repository\ngit clone [https://github.com/Shuuida/jutsu-lang.git](https://github.com/Shuuida/jutsu-lang.git)\ncd jutsu_lang\n\n# 2. Compile the engine applying extreme mathematical optimizations (Release)\ncargo build --release\n\n# The binary executable will be ready in: target/release/tgn.exe\n```\n\n### IDE Extension (VS Code / Cursor)\n\nTo enable native syntax highlighting (Burgundy/Orange Theme):\n\n1.  Navigate to the `/ide_extension` folder within the project.\n2.  Copy the `jutsu-lang` folder into your editor's extensions directory:\n      * **VS Code:** `%USERPROFILE%\\.vscode\\extensions\\`\n      * **Cursor:** `%USERPROFILE%\\.cursor\\extensions\\`\n3.  Restart the editor and open any `.ju` file.\n\n-----\n\n## ⚡ Extreme Acceleration (CUDA / Metal / Vulkan)\n\nJutsu is **hardware-agnostic**. It uses a dynamic library loading system. By default, Tengen Engine will process inference on your CPU. If you have dedicated hardware (GPU), Jutsu will absorb it automatically and transparently.\n\n**⚠️ Strict Requirement:** Jutsu v0.1.0 was compiled and linked to the C++ engine **llama.cpp build b8115**. You must use the exact binaries from that version to avoid memory structure conflicts (ABI/Segmentation Faults).\n\n**Instructions for NVIDIA GPUs (CUDA):**\n\n1.  Go to the official release: [llama.cpp Release b8115](https://github.com/ggerganov/llama.cpp/releases/tag/b8115).\n2.  Download the CUDA DLLs (e.g. `llama-b8115-bin-win-cuda-cu12.2-x64.zip`).\n3.  Extract the `ggml-cuda.dll` file (and its attached dependencies) and paste them into the same folder where `tgn.exe` is installed.\n4.  When running your script, the `absorb` directive will detect the CUDA backend and delegate the matrix loading to the VRAM.\n\n*(Apply the same process by downloading `ggml-vulkan.dll` if you use AMD or Intel graphics).*\n\n-----\n\n## 📖 In-Depth Syntax and IOP Reference\n\n### 1. Primitives and Dynamic Typing\n\nJutsu handles memory for you. It supports the standard types of any modern language:\n\n```jutsu\nlet name = \"Agent_01\"    // String\nlet threshold = 0.85        // Number (Float32 for tensor compatibility)\nlet active = true           // Boolean\nlet empty = null            // Null\nlet record = [1, 2, \"A\"] // Dynamic array\nlet config = {\"id\": 101}    // Dictionary (Hash Map)\n```\n\n### 2. Control Structures and Functions\n\nFlow control is straightforward and familiar (`if`, `while`). However, function declaration has a strict peculiarity in the Parser:\n\n**⚠️ The Return Rule:** In Jutsu, every function (`def`) **must** be explicitly closed with a `return` statement. If your function executes an action but does not need to return a mathematical value, you must close it with a `return \"\"` (empty string) or `return 0` to release the engine's Execution Frame.\n\n```jutsu\n// Loop and Conditionals\nwhile (active) {\n    if (threshold == 0.85) {\n        print(\"Limit reached\")\n        active = false\n    }\n}\n\n// Function Declaration (Note the mandatory return)\ndef greet_user(name) {\n    print(\"Starting protocol for: \" + name)\n    return \"\" // Mandatory for syntactic validity\n}\n```\n\n### 3. The IOP Core (Intelligence Management)\n\nThese directives replace classic object instantiation.\n\n  * **`vessel name = absorb(path, temp=x)`**\n      * *Function:* Loads a pre-compiled GGUF model into memory. The hosting (RAM/VRAM) is decided transparently here based on your hardware. The `temp` parameter controls entropy (creativity vs. determinism).\n  * **`name.infer(prompt, context, gbnf)`**\n      * *Function:* Triggers the \"Forward Pass\" on the GPU/CPU. Blocks the current thread until the full response is obtained. `gbnf` allows injecting formal grammars to force responses into strict JSON.\n  * **`rag(query, doc)`**\n      * *Function:* Primitive for *Retrieval-Augmented Generation*. Searches a local document for semantic or exact matches to inject as context.\n  * **`vessel name = hyper_quad(source_path, target_path, compression_type)`**\n      * *Function:* **Dynamic Hardware Quantization (On-The-Fly) \u0026 Auto-Injection.** It takes a massive, raw model (e.g., a 3GB Float16 file), compresses its tensors in real-time using all available CPU cores into a highly optimized bit-rate (like `\"Q4_K_M\"`), saves it to disk, and **instantly absorbs it** into the Engine's live memory under the assigned `name`. This turns Jutsu into a self-optimizing orchestrator capable of adapting heavy AI models to low-memory environments without manual developer intervention.\n\n### 4. Concurrent Orchestration and Mutex\n\nJutsu is designed to handle thousands of interactions natively.\n\n  * **`worker { ... }`**\n      * *Function:* Creates a *Shadow Worker*. Isolates local variables and executes the block in a background Tokio thread. Useful for creating autonomous \"Agents\" that live in parallel.\n  * **`share(value)` / `queue_push(value)`** and **`recv()` / `queue_pop()`**\n      * *Function:* Syntactic sugar for the Producer-Consumer pattern. Injects and extracts data from a **Global Atomic Memory Queue (Thread-Safe Deque)**. If `recv()` finds the queue empty, it safely returns `Null`.\n  * **`sleep(seconds)`**\n      * *Function:* Asynchronously pauses the current `worker` thread without blocking the OS main thread or the Tokio Event Loop. This is the cornerstone for creating **Daemon Patterns (Long Polling)**. It allows an agent to silently monitor a queue in the background with a 0% CPU footprint.\n  * **`shield(Model = \"mem\") { ... }`**\n      * *Function:* When a `worker` enters a `shield` block, it violently hijacks the hardware lock of the graphics card. Any other agent attempting to do `.infer()` will be safely suspended in RAM until the shield is released. Vital for emergency routines or High-Priority Core Agents.\n\n### 5. Skill Calling and System Tools (APIs)\n\n  * **`sys_exec(cmd)`**: Silently executes commands on the host terminal (OS) and returns the resulting String (ideal for coding agents, handle with responsibility).\n  * **`http_get(url)`**: Asynchronous GET requests to give the AI internet access.\n  * **`read_text(path)`**: Fast I/O reader to ingest memory from `.txt` or `.json` files.\n  * **`input(prompt)`**: Halts the thread and waits for dynamic keyboard input from a human user.\n  * **`veil(name) (port) { ... }` and `reply(val)`**: Boots up a native TCP server in Jutsu. Allows external web platforms to send requests to local Agents.\n\n### 6. The Mathematical Sieve (Hardware-Level GBNF)\n\nJutsu implements a strict, hardware-level grammar compiler that intercepts the token generation process directly in the VRAM (via the modern Sampler API). By passing an EBNF (Extended Backus-Naur Form) grammar to the `.infer()` method, you force the AI to produce exact, mathematically guaranteed structures (like 100% valid JSON), preventing hallucinated formats.\n\nJutsu supports **Multiline Strings** using triple quotes (`\"\"\"`), allowing for clean and readable grammar definitions with full native support for regex-like quantifiers (`*`, `+`, `?`) natively handled by the C++ engine.\n\n```jutsu\n// Clean definition of a strict JSON grammar\nlet grammar = \"\"\"\nroot ::= \"{\" ws \"\\\"status\\\"\" ws \":\" ws result \"}\"\nws ::= [ \\t\\n]*\nresult ::= [\"] \"OK\" [\"] | [\"] \"ERROR\" [\"]\n\"\"\"\n\nshield(Master = \"100%\") {\n    // The model is mathematically forced to only output {\"status\": \"OK\"} or {\"status\": \"ERROR\"}\n    let response = Master.infer(\"Evaluate this system...\", ctx, grammar)\n    return response\n}\n```\n\n### 7. Native MCP Server (Model Context Protocol)\n\nJutsu can operate as a high-performance backend via the Model Context Protocol (MCP). You can expose Jutsu functions (Tools) to external clients (like Python scripts, Claude Desktop, etc) using asynchronous JSON-RPC communication over TCP. This turns Jutsu into an invisible, highly efficient cognitive processing node.\n\n```jutsu\ndef analyze_ticket(params) {\n    let user_text = params[\"text_ticket\"]\n    \n    // ... execute shielded inference with GBNF ...\n    \n    // Returns the structured JSON directly to the external client\n    return json_result \n}\n\n// Boots a native asynchronous TCP server exposing the tool\nmcp_server(port = 8080) {\n    expose_tool(\n        name = \"extract_ticket_data\", \n        desc = \"Uses local AI to classify and structure support messages.\", \n        function = analyze_ticket\n    )\n}\n```\n\n-----\n\n## 🔀 Orchestration Flow: The \"Router\" Pattern\n\nThis test script demonstrates the use of queues (`share`/`recv`), the background Daemon pattern (`sleep`), and the Hardware Mutex (`shield`) operating in real life. It can also be found in the tests folder to try it out personally.\n\n```jutsu\nprint(\"\u003e\u003e\u003e JUTSU CORE: Asynchronous Tech Support Orchestrator \u003c\u003c\u003c\")\n\n// 1. Load the Central Brain (Shared and protected by the Mutex)\nvessel Master = absorb(\"Qwen2.5-Coder-1.5B-Instruct-Q4_K_M.gguf\", temp=0.0)\n\n// Blank context variables to respect the dynamic parser\nlet ctx = \"\"\nlet gbnf = \"\"\n\n// 2. LEVEL 1 AGENT (Processes the normal queue)\nworker {\n    print(\"[Level 1] Starting shift. Listening to the ticket queue...\")\n    let active = true\n    \n    while (active) {\n        // SYNTACTIC SUGAR: recv() now safely extracts from the queue\n        let ticket = recv() \n        \n        if (type_of(ticket) != \"Null\") {\n            print(\"\\n[Level 1] Ticket received: \" + ticket)\n            print(\"[Level 1] Thinking response...\")\n            \n            // If Level 3 has the shield, this will wait patiently (No Deadlocks)\n            let solution = Master.infer(ticket, ctx, gbnf)\n            print(\"[Level 1] Solution sent -\u003e \" + solution)\n        } else {\n            // DAEMON PATTERN (Long Polling):\n            // If the queue is empty, sleep for 1 second and ask again.\n            // This turns the Worker into a persistent background service.\n            sleep(1) \n        }\n    }\n}\n\n// 3. LEVEL 3 AGENT (Critical Emergency Response)\nworker {\n    let critical_alert = \"RED ALERT: The main database server just threw a 500 Error and went down. Suggest a console command to restart the service on Linux.\"\n    \n    // CRITICAL SECTION: We hijack the GPU for the Master model\n    shield(Master = \"100%\") {\n        print(\"\\n=======================================================\")\n        print(\"[SYSTEM] OVERRIDE SEQUENCE ACTIVATED BY LEVEL 3\")\n        print(\"[SYSTEM] Level 1 Agents on hardware pause...\")\n        print(\"=======================================================\")\n        \n        // Being inside the shield, 'infer' doesn't ask for the lock, it already holds it.\n        let emergency_anwser = Master.infer(critical_alert, ctx, gbnf)\n        \n        print(\"\\n[Level 3] MITIGATION PROTOCOL -\u003e \" + emergency_anwser)\n        print(\"=======================================================\\n\")\n    }\n    // Exiting the braces, the hardware lock is dropped, Level 1 resumes.\n}\n\n// 4. THE MAIN ROUTER (The Producer)\nprint(\"[Router] Receiving emails from users...\")\n\n// SYNTACTIC SUGAR: share() now safely pushes to the global queue\nshare(\"Answer shortly: My screen flickers when I open the web browser.\")\nshare(\"Answer shortly: I forgot my password for the human resources portal.\")\nshare(\"Answer shortly: How do I clear the cache on my computer?\")\n\nprint(\"[Router] 3 normal tickets queued.\\n\")\n\n// 5. The server anchor\nlet _anchor = input(\"\u003e\u003e\u003e Press ENTER to shut down the Enclave node servers... \u003c\u003c\u003c \\n\")\n```\n\n-----\n\n## 🗺️ Roadmap and Future Architecture\n\nThe engine is stable in its experimental phase (v0.2.0-alpha), but evolution continues. With the Mathematical Sieve (GBNF) and the MCP Server fully operational, the next major infrastructure milestone will be:\n\n* **GEP (Genome Evolution Protocol):** Leveraging the absolute stability of the hardware-level GBNF compiler, Jutsu will introduce native syntax for evolutionary agents. Instead of attempting to destructively mutate neural weights (Tensors), GEP will mutate the agent's \"Soul Configuration\" (The Genome: System Prompts, Temperatures, Bind Penalties, and RAG contexts). \n  \n  Background Tokio threads will spawn swarms of mutant agents and evaluate their responses. Because the GBNF ensures every mutant agent still outputs strict, parsable JSON regardless of how chaotic its parameters become, Tengen Engine will be able to run automated Fitness Loops, calculate scores, and crossbreed the best configurations dynamically. This will turn Jutsu into a self-optimizing, neuro-evolutionary swarm orchestrator natively running on local hardware.\n\n-----\n\n## 🤝 Conclusion and Contributions\n\nJutsu is not an attempt to replace mature languages like Python or Go. Its mission is to exist as the **Impassable Local Inference and Routing Layer** where cognitive models live, share atomic memory, and think concurrently on local hardware. Think of it as the \"pipeline\" for artificial intelligence agents.\n\nThis project is born from the philosophy of free engineering. It is **Open Source by and for the community**. The Artificial Intelligence ecosystem moves fast, and the scalability of Tengen Engine requires bold minds.\n\nEvery technical audit, *Pull Request*, bug report on the Lexer, Evaluator optimization, or architectural debate is deeply welcome. Help us forge a standard tool for Local Orchestration for ourselves!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuuida%2Fjutsu-lang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshuuida%2Fjutsu-lang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshuuida%2Fjutsu-lang/lists"}