Metadata-Version: 2.4
Name: nos
Version: 0.1.3
Summary: Node Orchestration System (NOS) - A declarative DSL for ROS2 robotics
Author: NOS Team
License: Apache-2.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: antlr4-python3-runtime>=4.13.0
Requires-Dist: jinja2>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: mypy>=0.950; extra == "dev"
Requires-Dist: flake8>=4.0.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: license
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# NOS: Node Orchestration System

A declarative domain-specific language (DSL) for ROS2 robotics development.

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache%202.0-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-pytest-yellow.svg)](CONTRIBUTING.md#running-tests)

## Overview

NOS reduces ROS2 boilerplate by 70-80% while maintaining full compatibility with existing ROS2 tooling. It provides:

- **Declarative syntax** for node, topic, and parameter definitions
- **Type-safe interfaces** with compile-time validation
- **Robust Expression Parsing**: Full support for mathematical and logical operators with standard precedence.
- **Lifecycle management** integrated into the language
- **Launch file generation** from unified definitions
- **Code generation** for both Python and C++ (C++ in Phase 2)

## Current Progress
For detailed status on implementation, testing, and roadmap, see [progress.md](progress.md).

### Why NOS?

| Aspect | Native ROS2 Python | NOS | Reduction |
|--------|-------------------|----------|-----------|
| Simple Node | ~60 lines | ~15 lines | 75% |
| Lifecycle Node | ~120 lines | ~25 lines | 79% |
| Launch File | ~80 lines | ~20 lines | 75% |
| Parameters (10 params) | ~50 lines | ~10 lines | 80% |

## Requirements

- Python 3.8 or higher
- ROS2 (for runtime usage)
- ANTLR4 Python runtime (installed automatically)

## Installation

### From Source

1. Clone the repository:
   ```bash
   git clone https://github.com/your-org/nos.git
   cd nos
   ```

2. Install in development mode:
   ```bash
   pip install -e .
   ```

### Adding to PATH

To use the `nos` command from anywhere, ensure your Python script directory is in your system's PATH.

**Windows:**
1. Search for "Edit the system environment variables".
2. Click "Environment Variables".
3. Under "User variables", find `Path` and click "Edit".
4. Add the path to your Python Scripts folder (e.g., `%APPDATA%\Python\Python3x\Scripts`).

**Linux/macOS:**
Add this to your `.bashrc` or `.zshrc`:
```bash
export PATH="$PATH:/home/user/.local/bin"
```

## Quick Start: Turtlesim Circle

NOS allows you to define, compile, and run ROS2 nodes directly.

### 1. Create `circle.node`

```nos
package turtlesim_example
version "0.1.0"
depends: ["rclpy", "geometry_msgs"]

node CircleGenerator {
    publications {
        cmd_vel: geometry_msgs::Twist @topic("/turtle1/cmd_vel")
    }

    on_init -> {
        self.get_logger().info("Starting circular motion...")
        # Create a timer to publish at 10Hz
        self.create_timer(0.1, self.timer_callback)
    }

    on timer_callback() -> {
        msg = Twist()
        msg.linear.x = 2.0
        msg.angular.z = 1.0
        self.cmd_vel.publish(msg)
    }
}
```

### 2. Run Directly

You can skip the manual build process and run the node immediately from the source file:

```bash
# Start Turtlesim first in another terminal:
# ros2 run turtlesim turtlesim_node

# Compile and run the NOS node instantly
nos circle.node --run
```

The `--run` flag automatically handles code generation, temporary workspace setup, and execution.

## Project Structure

```
nos/
├── grammar/          # ANTLR4 generated parser files (auto-generated)
├── ast/              # Abstract Syntax Tree
├── semantic/         # Semantic analysis
├── codegen/          # Code generation
├── runtime/          # Runtime library
├── compiler/         # Compilation pipeline
└── security/         # Security validation
tests/                # Test suite
├── unit/             # Unit tests
└── integration/      # Integration tests
```

**Note**: Files in `grammar/` are auto-generated by ANTLR4 from grammar definitions. Do not edit them manually.

## File Extensions

- `.nos` - System definition files (packages, imports, launch declarations)
- `.node` - Node component definitions
- `.interface` - Message/service/action interface definitions

## Key Features

### 1. Declarative Parameters

```nos
parameters {
    max_velocity: float = 1.0 @range(0.0, 5.0) @unit("m/s")
    enable_filter: bool = true
}
```

### 2. Type-Safe Topics

```nos
subscriptions {
    scan: sensor_msgs::LaserScan @topic("/scan")
}

publications {
    processed: sensor_msgs::LaserScan @topic("/processed")
}
```

### 3. Launch File Generation

```nos
launch NavigationStack {
    group sensors @namespace("sensors") {
        lidar: LidarDriver { ... }
        camera: CameraDriver { ... }
    }
}
```

### 4. Lifecycle Integration

```nos
node MyNode {
    lifecycle: managed  # Enables lifecycle management
    
    on_init { ... }
    on_shutdown { ... }
}
```

## Compilation Pipeline

```
NOS Source
      |
      v
+-------------+
|   Parse     |  ANTLR4 lexer/parser
|  (ANTLR4)   |  generates parse tree
+------+------+
       |
       v
+--------------+
|  Build AST   |  Parse tree converted
|              |  to typed AST
+------+-------+
       |
       v
+--------------+
|   Analyze    |  Semantic analysis
|              |  validates symbols
+------+-------+
       |
       v
+-------------+
|  Generate   |  Target code generated
|  (Python)   |  for ROS2 nodes
+-------------+
```

### CLI Usage

```bash
# Basic compilation
nos input.node -o output_dir/

# With verbose output
nos input.node -v

# Dry run (validate only)
nos input.node --dry-run

# Multiple files
nos file1.node file2.nos -o generated/

# Show version
nos --version
```

## Development

### Running Tests

```bash
# Run all tests
pytest

# With coverage
pytest --cov=nos --cov-report=term-missing

# Run specific test file
pytest tests/unit/test_ast_builder.py
```

### Code Style

```bash
# Format code with black
black nos/ tests/

# Type checking
mypy nos/

# Linting
flake8 nos/ tests/
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed contribution guidelines.

## Status

### Phase 1: Core Language (Complete) ✓

- [x] ANTLR4 grammar definitions
- [x] AST and semantic analyzer
- [x] Python code generator
- [x] Launch file transpiler
- [x] Runtime library
- [x] Security validation
- [x] Callback syntax & custom events (Issue #6)

### Phase 2: Extended Features (Planned)

- [ ] C++ code generator
- [ ] Enhanced IDE support (LSP)
- [ ] Visual diagram generation
- [ ] Package management tools

See [CHANGELOG.md](CHANGELOG.md) for detailed release information.

## Documentation

- [Architecture Overview](ros2_dsl_architecture.md) - Detailed design document
- [Contributing Guide](CONTRIBUTING.md) - Development setup and guidelines
- [Changelog](CHANGELOG.md) - Version history and changes

## License

Apache License 2.0 - See [LICENSE](LICENSE) for details.

## Acknowledgments

NOS was inspired by the verbosity challenges in ROS2 development and aims to provide a more ergonomic interface while maintaining full compatibility with the ROS2 ecosystem.
