# Aether Framework

> Human-readable, AI-interpretable, machine-consumable.

[![PyPI version](https://badge.fury.io/py/aether-py.svg)](https://pypi.org/project/aether-py/)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: FSL-1.1-MIT](https://img.shields.io/badge/License-FSL--1.1--MIT-blue.svg)](https://fsl.software/)

Aether is a lightweight, schema-driven framework for structured content authoring and validation with AI assistance. It enables humans and AI to collaborate on creating, validating, and distributing structured content.

## Features

- ✅ **Schema Validation** - JSON Schema Draft 7 with custom Aether extensions (`media`, `markdown`)
- ✅ **Entity Collections** - Hierarchical content organization with automatic reference resolution
- ✅ **Bundle Distribution** - Package complete projects as portable `.aetherpack` archives
- ✅ **AI Integration** - Native support for Cursor AI and Model Context Protocol (MCP)
- ✅ **CLI & Python API** - Use from command line or integrate into Python applications
- ✅ **Comprehensive** - Project scaffolding, introspection, validation context, and more

## Installation

```bash
pip install aether-py
```

## Quick Start

### Define a Schema

Create `blog.aether`:

```yaml
id: blog
spec_version: "1.0.0"
version: "1.0.0"
title: Blog

structure:
  posts:
    type: array
    items:
      $ref: "#/objects/Post"

objects:
  Post:
    type: object
    properties:
      title: { type: string }
      content: { type: markdown }
      author: { type: string }
      published: { type: boolean }
```

### Create Content

```bash
# Create project structure
aether scaffold blog.aether my-blog --examples

# Validate project
aether validate-project my-blog

# Bundle for distribution
aether bundle my-blog -o blog.aetherpack
```

### Use in Python

```python
import aether

# Load and validate
schema = aether.load_schema("blog.aether")
project = aether.open_bundle("blog.aetherpack")
aether.validate_project(project, schema)

# Access resolved content
for post in project['posts']:
    print(f"Title: {post['title']}")
    print(f"Author: {post['author']}")
```

## Use Cases

### 📚 Documentation & Reports
- Technical documentation with automatic cross-references
- Corporate reports with validated data structures
- Static site generators with schema-driven content

### 🎨 Interactive Digital Experiences
- Educational simulations with validated entity systems
- Narrative platforms with branching storylines
- Interactive media with decision trees

### 🧠 Knowledge Management
- Portable content packages for AI agents
- Validated knowledge bases
- Schema-driven data distribution

## Documentation

- 📖 [Getting Started](docs/getting-started/quickstart.md)
- 📘 [Concepts](docs/concepts/index.md) - Schemas, entities, collections
- 🔧 [CLI Reference](docs/cli/index.md) - Command-line tools
- 🐍 [Python API](docs/api-reference/index.md) - Library reference
- 🤖 [AI Integration](docs/advanced/ai-integration.md) - Cursor AI & MCP
- 📄 [Whitepaper](AETHER-WHITEPAPER.md) - Vision and architecture

## Examples

Check out the [`examples/`](examples/) directory for complete working projects:

- **aether-docs** - Self-documenting: Aether's own documentation as an Aether project

## Development

```bash
# Clone repository
git clone https://github.com/jintra-jayce/aether.git
cd aether

# Install dependencies
pip install -e .

# Run tests
pytest
```

## VS Code Extension

For the best development experience, install [**aether-vscode**](https://github.com/jintra-jayce/aether-vscode):

- Real-time schema validation
- IntelliSense for entity references
- AI-powered content assistance
- Visual project navigation

## License

Functional Source License, Version 1.1, MIT Future License (FSL-1.1-MIT)

- Free to use for any purpose except creating competing products
- Automatically converts to MIT License after 2 years (January 1, 2027)
- See [LICENSE](LICENSE) for full terms

## Contributing

Contributions welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before submitting pull requests.

## Contact

- **Issues**: [GitHub Issues](https://github.com/jintra-jayce/aether/issues)
- **Email**: jayce@jintra.io
- **License Questions**: jayce@jintra.io

## Acknowledgments

Copyright © 2025 Jintra Software Solutions LLC

