Metadata-Version: 2.4
Name: genitus
Version: 0.0.1
Summary: Reservation package for the Genitus AI-native programming language. The working CLI is built from the Rust workspace.
Author-email: Miguel Ocque <hi@cumulush.com>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Cumulus-s/genitus
Project-URL: Repository, https://github.com/Cumulus-s/genitus
Project-URL: Issues, https://github.com/Cumulus-s/genitus/issues
Keywords: ai,language,schema,trace,cli
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Rust
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE-APACHE
License-File: LICENSE-MIT
License-File: NOTICE
Dynamic: license-file

# Genitus

Genitus is a small schema-first programming language kernel for AI assistants, LLM workflows, and agent tooling.

## Status

Genitus v0.0.1 is the final 0.0.1 developer-preview release string. It is not a stable 1.0 release. The language, AST JSON, schema JSON, diagnostics, trace format, and CLI behavior may still change before v1.0.0.

## What Genitus Can Do Today

- Parse `.gen` source files.
- Check names, types, tool calls, task `uses` clauses, and `limits max_tool_calls`.
- Print deterministic JSON AST output.
- Print JSON Schema-like output for declared types, tools, tasks, AST metadata, and trace metadata.
- Run one selected task in a deterministic interpreter.
- Call only mocked tools supplied by the CLI.
- Validate task input JSON, mocked tool output JSON, and final output JSON.
- Write deterministic JSONL execution traces.
- Emit human-readable or JSON diagnostics.

## What Genitus Cannot Do Yet

Genitus v0.0.1 does not call live models, access the network from programs, run shell commands from programs, write arbitrary files from programs, implement MCP, manage packages, use memory or RAG, orchestrate multiple agents, provide an LSP, format code, compile to WebAssembly, or compile to native code.

The language also does not include loops, classes, inheritance, macros, generics, async, user-defined functions, arrays, unions, optional fields, or enums.

## Install From Source

Prerequisites: stable Rust and Cargo. The repository includes `rust-toolchain.toml`, which selects stable Rust and installs `rustfmt` and `clippy`.

From the repository root:

```bash
cargo build --workspace
cargo test --workspace
cargo run -p genitus-cli -- --version
```

The working CLI Cargo package is named `genitus-cli`. It builds two binaries: `genitus` and `gen`. The public version output is `genitus 0.0.1`.

More detail: [docs/install.md](docs/install.md).

## Quickstart

Check the ticket example:

```bash
cargo run -p genitus-cli -- check examples/ticket.gen
```

Inspect its AST and schema:

```bash
cargo run -p genitus-cli -- ast examples/ticket.gen --json
cargo run -p genitus-cli -- schema examples/ticket.gen --json
```

Run it with a mocked tool response and write a trace:

```bash
cargo run -p genitus-cli -- run examples/ticket.gen --input examples/ticket.input.json --mock-tool classify_text=examples/classify_response.json --trace /tmp/genitus-ticket-trace.jsonl
```

Expected output:

```json
{
  "category": "account_access",
  "confidence": 0.91
}
```

More detail: [docs/quickstart.md](docs/quickstart.md).

## Examples

- `examples/ticket.gen`: classifies a support ticket.
- `examples/sentiment.gen`: analyzes sentiment.
- `examples/route_request.gen`: uses named multi-argument tool calls.
- `examples/support_multi_task.gen`: demonstrates `--task <task_name>` for a multi-task file.

Each example has input JSON and mocked tool output JSON next to the `.gen` file.

## Safety Posture

Genitus v0.0.1 is deterministic and intentionally limited:

- Programs cannot access the network.
- Programs cannot execute shell commands.
- Programs cannot read or write arbitrary files.
- Tools only return mocked JSON provided through `--mock-tool`.
- Tools must be declared and listed in the selected task `uses` clause.
- Inputs, mocked tool outputs, and final outputs are validated.
- Trace files are written only when the CLI user passes `--trace`.

Genitus v0.0.1 is not a production sandbox, policy engine, MCP server, or autonomous agent runtime. See [SECURITY.md](SECURITY.md).

## Documentation

- [Install](docs/install.md)
- [Quickstart](docs/quickstart.md)
- [Language](docs/language.md)
- [Specification](SPEC.md)
- [Schema contract](SCHEMA.md)
- [Trace contract](TRACE.md)
- [Release process](docs/release-process.md)
- [GitHub settings checklist](docs/github-settings.md)
- [AI contribution policy](docs/ai-contribution-policy.md)

## Contributing

Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.

## Security Reporting

Report suspected security issues privately. See [SECURITY.md](SECURITY.md) for the current reporting path.

## License

Genitus is licensed under either MIT or Apache-2.0, at your option. See [LICENSE-MIT](LICENSE-MIT), [LICENSE-APACHE](LICENSE-APACHE), [LICENSE](LICENSE), and [NOTICE](NOTICE).

Programs written in Genitus, generated AST JSON, generated schema JSON, generated traces, and outputs produced by running Genitus programs are not claimed by the Genitus project solely because they were created with Genitus.
