Metadata-Version: 2.4
Name: gsam
Version: 0.2.2
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://gitlab.com/graphscript/gsam
Project-URL: Repository, https://gitlab.com/graphscript/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
Requires-Dist: langex>=0.4.6
Dynamic: license-file

# GSAM

GSAM (GraphScript Assembly Markup) is an orchestration language and execution engine designed around a graph-based computation model.

## Installation

```sh
pip install gsam
```

## Overview

GSAM describes how capabilities are connected together rather than how those capabilities are implemented.

A GSAM program is a graph of nodes:
- nodes define reusable operations,
- execution nodes define flow,
- values connect operations,
- Materials provide implementations.

The core engine remains minimal while external Materials provide domain-specific behavior.

## Materials

Materials are external modules that extend GSAM capabilities.

A Material can provide:
- application logic,
- integrations,
- data operations,
- system operations,
- reusable execution nodes.

GSAM focuses on orchestration. Materials focus on implementation.

## Syntax

GSAM uses indentation to represent structure.

Core identifiers:

- `?` Comment
- `$` Import Material
- `&` Import GSAM file
- `!` Create value
- `*` Define node
- `-` Execute node
- `+` Provide argument
- `=` Set value or return value
- `:` Define steering
- `>` Define steering path

For complete syntax details, refer to the semantics example:

`samples/semantics.gsam`

## Example

```gsam
$ console

- log
  + Hello, GSAM!
```

## Execution Model

GSAM programs are compiled into an execution graph.

Execution consists of:

- Parsing source
- Building intermediate representation
- Constructing graph nodes
- Scheduling execution
- Running node implementations

GSAM does not rely on simple line-by-line execution. Nodes are processed according to their identity and execution semantics.

## Architecture

### Compiler Pipeline

- Source parsing
- Intermediate Representation (IR)
- Graph construction
- Execution planning

### Runtime

- Execution queue
- Execution groups
- Runtime context
- Memory storage

### Material System

The Material system allows GSAM to remain extensible without requiring the core engine to know every possible capability.

## Design Philosophy

GSAM is built around:

- Orchestration over implementation
- Composition over duplication
- Explicit graph structure
- Small and extensible core
- Separation between language and runtime behavior

Complex behavior belongs in Materials. GSAM connects those behaviors together.

## Status

GSAM is under active development.

The language, runtime, and APIs may evolve as the project matures.

## Links

- PyPI: https://pypi.org/project/gsam/
- GitLab (Main): https://gitlab.com/graphscript/gsam
- GitHub: https://github.com/graphscript-labs/gsam

---

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

