Metadata-Version: 2.4
Name: gsam
Version: 0.1.3
Summary: Compiler toolchain for the GSAM language.
Author: AttAditya
License: MIT License
        
        Copyright (c) 2026 AttAditya
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/graphscript-labs/gsam
Project-URL: Repository, https://github.com/graphscript-labs/gsam
Keywords: compiler,language,gsam,graphscript
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# [GSAM](https://pypi.org/project/gsam/)

GSAM compiler and execution engine

[![PyPI](https://img.shields.io/pypi/v/gsam?style=for-the-badge&logo=pypi)](https://pypi.org/project/gsam/)
[![GitHub](https://img.shields.io/badge/GitHub-repository-black?style=for-the-badge&logo=github)](https://github.com/graphscript-labs/gsam)

## Installation

```sh
pip install gsam
```

## About

GSAM is a compiler and execution engine built around a graph-based computation model. It is designed for extensibility, where external “Materials” define behavior and execution logic in a modular way.

Instead of traditional linear execution, GSAM represents programs as graphs of nodes, enabling flexible control flow, parallel execution patterns, and pluggable runtime behavior.

## Syntax Overview

Refer to the [Semantics Example](./samples/semantics.gsam) for detailed syntax descriptions and usage.

```gsam
? comment block (multi-line via indentation)
  lines starting with indentation are treated as part of the comment

- parent node
  = variable assignment
  @ keyword_argument
    + value
  + positional_argument
  > next node option


```

## Example

### Hello World

```gsam
? use console material
$ console

? "log" node comes from "console"
- log
  + "Hello, GSAM!"
```

## Architecture

GSAM is built as a graph-native execution system with layered components:

### Pipeline

Source code flows through:
- Parsing
- Intermediate Representation (IR)
- Graph construction
- Execution

### Execution Engine

- Execution Queue (node scheduling)
- Execution Clusters (parallel groups)
- Execution Stack (scoped runtime context)
- Memory Bank (runtime state storage)

### Materials System

- External modules defining execution behavior
- Plug-in style extensibility
- Core engine remains minimal and generic

### Core Artifacts

- Data nodes (computation units)
- Execution units (runtime tasks)
- Memory structures (state persistence)

## Design Philosophy

GSAM follows a minimal and explicit design approach:

- Graph-native execution model
- Extensible through external modules called “Materials”
- Minimal assumptions in the core engine
- Clear separation between syntax, execution, and behavior

## Status

GSAM is under active development.  
The architecture and APIs may evolve as the system matures.

## Links

- PyPI: https://pypi.org/project/gsam/
- GitHub: https://github.com/graphscript-labs/gsam
- License: https://github.com/graphscript-labs/gsam/tree/main/LICENSE

---

> _Made with <3 by [AttAditya](https://github.com/AttAditya)_
