Metadata-Version: 2.4
Name: inthon
Version: 0.1.0
Summary: Agent-level programming language for AI-native workflows
Project-URL: Homepage, https://harvatechs.github.io/inthon/
Project-URL: Repository, https://github.com/harvatechs/inthon
Project-URL: Documentation, https://harvatechs.github.io/inthon/
Author-email: HarVa DeepLabs <deeplabs@harvatechs.com>
License: Apache-2.0
License-File: LICENSE
Keywords: agent,ai,dsl,llm,programming-language,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.11
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: lark>=1.1.9
Requires-Dist: pydantic>=2.7.0
Requires-Dist: rich>=13.7.0
Requires-Dist: structlog>=24.1.0
Requires-Dist: typer>=0.12.0
Provides-Extra: data
Requires-Dist: pandas>=2.2.0; extra == 'data'
Requires-Dist: polars>=0.20.0; extra == 'data'
Requires-Dist: pyarrow>=16.0.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.2.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: ml
Requires-Dist: numpy>=1.26.0; extra == 'ml'
Requires-Dist: torch>=2.3.0; extra == 'ml'
Requires-Dist: transformers>=4.40.0; extra == 'ml'
Description-Content-Type: text/markdown

![INTHON Banner](documents/banner.png)

# INTHON: Agent-Level Programming Language Layer

[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-blue)](pyproject.toml)
[![Tests Status](https://img.shields.io/badge/tests-109%20passed-success)](tests/)
[![Type Checking: Mypy](https://img.shields.io/badge/type--checking-mypy--clean-success)](pyproject.toml)
[![Code Style: Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![Website Portal](https://img.shields.io/badge/website-live-success)](https://harvatechs.github.io/inthon/)

**INTHON** (Intelligent + Python) is a Python-hosted language layer designed specifically for AI-native workflows, tool orchestration, and capability-bounded execution. By representing agent execution intent as structured, deterministic code rather than unstructured natural language or verbose JSON/XML, INTHON reduces token footprint, validates schemas statically, and guarantees absolute sandbox safety.

---

## Table of Contents

- [1. Motivation \& Core Concept](#1-motivation--core-concept)
  - [Architectural Comparison](#architectural-comparison)
- [2. Execution \& Compilation Pipeline](#2-execution--compilation-pipeline)
  - [Compiler Stages](#compiler-stages)
- [3. Language Reference \& Syntax Spec](#3-language-reference--syntax-spec)
  - [Variable \& Constant Declarations](#variable--constant-declarations)
  - [Structured Agent Blocks](#structured-agent-blocks)
  - [Agent Primitives](#agent-primitives)
  - [PyBridge: Secure Python Interoperability](#pybridge-secure-python-interoperability)
- [4. Sandbox \& Security Architecture](#4-sandbox--security-architecture)
  - [Module Restrictions](#module-restrictions)
  - [Policy Guard Core](#policy-guard-core)
- [5. Installation \& Quick Start](#5-installation--quick-start)
- [6. Learner Documentation \& Tutorials](#6-learner-documentation--tutorials)
- [7. Benchmark Verification \& Performance](#7-benchmark-verification--performance)
- [8. CLI Tooling Reference](#8-cli-tooling-reference)
- [9. Development \& Verification](#9-development--verification)
  - [Community Guidelines](#community-guidelines)
- [10. Repository Architecture](#10-repository-architecture)
- [11. License](#11-license)

---

## 1. Motivation & Core Concept

Traditional AI agent designs rely on LLMs outputting fragile JSON, markdown blocks, or raw Python code to trigger actions. These approaches lead to:
1. **Token Bloat**: Redundant syntax in JSON schemas and natural language formatting.
2. **Side-Effect Risks**: Executing raw Python exposes the underlying OS, filesystems, and networks to arbitrary compromise.
3. **Audit Hardness**: Non-deterministic agent loops cannot be easily replayed, analyzed, or restricted post-generation.

**INTHON** introduces a lightweight, formal language block that bridges LLM reasoning with secure host computation:
* **Token-Efficient Grammar**: Built using an optimized EBNF format using Lark, making it extremely easy for LLMs to generate cleanly.
* **Capability-Based Sandbox**: Strict runtime policies control network access, disk writes, memory limits, and module imports.
* **Traceable Execution**: Out-of-the-box JSON trace trees logging every expression evaluation, tool transaction, and cost accumulation.

### Architectural Comparison

| Metric / Feature | JSON Tool Calling | Raw Python Code Gen | INTHON Language Layer |
| :--- | :--- | :--- | :--- |
| **Token Efficiency** | Poor (heavy JSON schema overhead) | Moderate (verbose syntax boilerplate) | **Excellent** (minimal EBNF footprint) |
| **Execution Safety** | Safe but highly restricted | Dangerous (arbitrary OS execution) | **Strictly Sandboxed** (fine-grained capabilities) |
| **Control Flow** | None (requires multi-turn LLM loops) | Turing Complete | **Turing Complete** (restricted loops & branches) |
| **Verification** | Runtime parsing only | Runtime execution only | **Static Type & AST Analysis** |
| **Replay & Audit** | Difficult | Impossible | **Deterministic JSON Execution Tracing** |

---

## 2. Execution & Compilation Pipeline

Below is the compilation and execution pipeline showing how an INTHON script compiles and executes within the sandboxed host environment.

```mermaid
flowchart TD
    subgraph Frontend [Compilation Frontend]
        A[INTHON Source Code] --> B[Lark Lexer & Parser]
        B --> C[AST Generation]
        C --> D[Semantic Analyzer]
    end

    subgraph Security [Capability Guard]
        D --> E[Policy & Sandbox Engine]
        E --> F[Tool Schema Validator]
    end

    subgraph Backend [Sandboxed Backend]
        F --> G[IR Builder]
        G --> H[AST-Walking Interpreter]
        H --> I[PyBridge Sandbox]
    end

    subgraph Outputs [Audit & Observability]
        I --> J[Replayable JSON Trace]
        I --> K[Execution Outputs]
    end

    style Frontend fill:#1f2937,stroke:#3b82f6,color:#fff
    style Security fill:#1f2937,stroke:#ef4444,color:#fff
    style Backend fill:#1f2937,stroke:#10b981,color:#fff
    style Outputs fill:#1f2937,stroke:#f59e0b,color:#fff
```

### Compiler Stages:
1. **Lex & Parse**: Tokenizes and validates grammar constraints using Lark's Earley/LALR parser engine.
2. **AST Generation**: Translates concrete parses into an immutable abstract syntax tree representing expressions and declarations.
3. **Semantic Analyzer**: Resolves scope bindings, checks static type annotations, and catches undeclared tools or modules before running.
4. **Policy & Guard**: Applies configuration constraints (e.g. rate limits, billing caps, execution timeouts).
5. **Sandbox Runtime**: Evaluates lowered code, intercepts side-effect-prone system calls, and maps secure functions to the host OS.

---

## 3. Language Reference & Syntax Spec

### Variable & Constant Declarations
Variables are declared using `let` (mutable) or `const` (immutable), with optional type annotations:

```inth
let name: str = "INTHON"
let version: float = 0.1
const max_retries: int = 3

// Collections
let models: list[str] = ["gpt-4o", "gemini-3.5", "claude-3"]
let metadata: dict[str, any] = {"accuracy": 0.94, "epochs": 10}
```

### Structured Agent Blocks
An `agent` block encapsulates the goal, typed boundary interfaces, policies, capabilities, and execution plans:

```inth
agent Researcher {
    goal "Retrieve recent papers on room-temperature superconductors"
    inputs {
        query: str
        limit: int
    }
    outputs {
        papers: list[dict]
    }
    
    use tool web.search
    
    policy {
        max_tool_calls: 10
        max_cost_usd: 0.05
    }
    
    plan {
        let raw_results = web.search(query: query, count: limit)
        return raw_results
    }
}
```

### Agent Primitives

#### 1. Approval Gateways
Requires human intervention before triggering a critical execution node (e.g., executing writes or calling payment gateways):
```inth
approve stripe.charge before make_payment
```

#### 2. Episodic Memory Operations
Persists facts to long-term memory or semantic caches during a session run:
```inth
remember "Superconductors show zero electrical resistance at critical temperatures" in semantic_memory
let fact = recall "superconductor properties" from semantic_memory
```

#### 3. Error Handling and Resiliency
Ensures workflows don't fail silently under API instability or rate limits:
```inth
retry 3 with backoff exponential {
    let response = web.search(query)
    guard response.status == 200
} catch error {
    return "Failed after 3 attempts: " + error.message
}
```

---

### PyBridge: Secure Python Interoperability
INTHON provides a highly controlled gateway to the host Python ecosystem. Modules must be declared via the `use py` syntax:

```inth
use py.numpy as np
use py.pandas as pd

let data = [1.0, 2.0, 3.0, 4.0]
let mean = np.mean(data)
```

---

## 4. Sandbox & Security Architecture

The sandbox intercepts all execution requests and runs them through three security validation layers:

1. **Static Validation**: Rejects programs referencing low-level system modules (`os`, `sys`, `subprocess`) before evaluation.
2. **Import Hook Filter**: PyBridge wraps imported modules in a secure proxy object (`InthonPyObject`), intercepts attribute/method requests, and validates them against the active execution policy.
3. **Resource Metering**: Enforces strict execution timeouts, tool invocation quotas, and financial cost limits (defined in `inthon.toml`).

### Module Restrictions

* **Standard Allowed Modules**: `numpy`, `pandas`, `math`, `json`, `collections`, `datetime`
* **Blocked Modules**: `os`, `sys`, `subprocess`, `ctypes`, `socket`, `builtins.eval`, `builtins.exec`

### Policy Guard Core

Any attempt to call a blocked package or exceed allocated limits triggers a `PolicyViolationError` and immediately halts execution, rolling back changes and logging the event in the trace log.

---

## 5. Installation & Quick Start

### Prerequisites
* Python `>= 3.11`
* Pip (python package installer)

### Installing from Source
Clone the repository and install it in developer mode:

```bash
git clone https://github.com/harvatechs/inthon.git
cd inthon
pip install -e .[dev,data,ml]
```

### Running Your First Program
Create a file named `agent.inth`:

```inth
// agent.inth
let threshold = 0.85
let confidence = 0.92

if confidence > threshold {
    return "Validation Success"
} else {
    return "Validation Failure"
}
```

Run it via the CLI:
```bash
inthon run agent.inth
```

---

## 6. Learner Documentation & Tutorials

If you want to learn INTHON step-by-step, we have created an **[Interactive Developer Guide Portal](https://harvatechs.github.io/inthon/guide.html)** and an offline **[Official Learner Documentation](learn/README.md)** directory. Follow the tutorials sequentially to master the language:

* **[Part 1: Getting Started](https://harvatechs.github.io/inthon/guide.html#guide-part1)**: Prerequisites, environment setup, and CLI reference guide.
* **[Part 2: Syntax Basics & Types](https://harvatechs.github.io/inthon/guide.html#guide-part2)**: Variables (`let`), constants (`const`), basic types, functions, and implicit returns.
* **[Part 3: Agents & Tools](https://harvatechs.github.io/inthon/guide.html#guide-part3)**: Creating structured agent blocks, goal definitions, and security policies.
* **[Part 4: PyBridge Interoperability](https://harvatechs.github.io/inthon/guide.html#guide-part4)**: Safe Python library imports, allowable namespaces, and sandbox mechanics.
* **[Part 5: Advanced Features](https://harvatechs.github.io/inthon/guide.html#guide-part5)**: Approval gateways, episodic memory systems, and exponential backoff retry loops.

For the deep compiler mechanics, Lark parsing grammar, and security wraps, refer to the **[Technical Specification & Benchmarks Report](https://harvatechs.github.io/inthon/spec.html)**.

---

## 7. Benchmark Verification & Performance

We evaluate INTHON's value across three dimensions: token usage efficiency, execution latency, and safety sandbox strength. For the full benchmark configuration and complete raw datasets, please refer to the **[Benchmark Report README](benchmarks/README.md)**.

### A. Token Efficiency (LLM Optimization)
Using Lark LALR parsing, INTHON represents agent workflows far more compactly than JSON schemas or natural language specifications.

| Task / Representation | Natural Language | JSON Tool Plan | Python Code Gen | INTHON Layer | Reduction vs NL |
| :--- | :---: | :---: | :---: | :---: | :---: |
| **Research Report** | 120 tokens | 90 tokens | 75 tokens | **52 tokens** | **56.67%** |
| **CSV Summary** | 95 tokens | 80 tokens | 65 tokens | **54 tokens** | **43.16%** |
| **Approval Gate** | 80 tokens | 70 tokens | 60 tokens | **19 tokens** | **76.25%** |

![Token Efficiency Graph](docs/assets/graphs/token_efficiency.png)

### B. Sandbox Execution Latency
Compiling INTHON code to Intermediate Representation (IR) and executing it inside our AST sandbox introduces negligible latency:

![Latency Graph](docs/assets/graphs/latency.png)

### C. Security Sandbox Robustness
We validated INTHON against 6 critical exploit attack vectors designed to run arbitrary shell commands, bypass billing quotas, or force payment gates. 

![Safety Graph](docs/assets/graphs/safety.png)

> **Conclusion**: INTHON achieves a **100% block rate** against all critical sandbox escapes while reducing agent prompt cost and generation latency by up to **76%**.

---

## 8. CLI Tooling Reference

The package ships with a CLI tool (`inthon`):

```
Usage: inthon [OPTIONS] COMMAND [ARGS]...

  INTHON — agent-level programming language

Options:
  --help  Show this message and exit.

Commands:
  run    Execute an INTHON program.
  check  Lint and type-check without executing.
  ast    Print the parsed Abstract Syntax Tree.
  ir     Print the lowered IR as JSON.
  fmt    Format an INTHON file (standardizes spacing and newlines).
```

### Command Examples

**Running with audit tracing:**
```bash
inthon run agent.inth --trace-out trace.json --max-cost 0.50
```

**Static syntax and type analysis:**
```bash
inthon check agent.inth
```

**Formatting source files:**
```bash
inthon fmt agent.inth --write
```

---

## 9. Development & Verification

For development, install all testing and QA tooling:
```bash
pip install -e .[dev]
```

### Running Tests
Execute the full test suite using pytest:
```bash
python -m pytest --cov=inthon --cov-report=term-missing
```

### Linting and Formatting
Lint and format checks are handled via Ruff:
```bash
# Linting
python -m ruff check .

# Formatting
python -m ruff format --check .
```

### Community Guidelines
To maintain a high standard of professional contribution, please review these standard files:
* **[Code of Conduct](CODE_OF_CONDUCT.md)**: Contributor standards and scope of behavior.
* **[Contributing Guidelines](CONTRIBUTING.md)**: Local development environment, branch rules, and style reviews.
* **[Security Policy](SECURITY.md)**: Guidelines for disclosing security vulnerabilities or sandbox escapes.

---

## 10. Repository Architecture

```
inthon/
├── ast/             # AST Node Definitions & Visitor Interfaces
├── lexer/           # Token Definitions & Lexer Parser Engine
├── parser/          # Lark EBNF parser & transformer
├── ir/              # Intermediate Representation lowering & serializer
├── semantic/        # Scope Analyzer, Type Checker, and Permissions
├── policy/          # Policy Engine & Human-in-the-loop approvals
├── pybridge/        # Sandboxed Python Import Hook Interop Layer
├── runtime/         # Interpreter Sandbox & Values Representation
├── tools/           # Tool Registry, Schema Validator, and Core Libs
├── cli.py           # CLI Command Implementation
└── version.py       # Package Version Reference
```

---

## 11. License

This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for the full license text.
