Metadata-Version: 2.4
Name: jos-core
Version: 2.1.1
Summary: Reference kernel for .jos 2.1 documents: validate, normalize, run atoms and flows (engines shell and jos), directories, PAL, per-run ledger and receipts. Python >= 3.10, 0 dependencies.
Author: JOSFOX maintainers
License: Apache-2.0
Project-URL: Homepage, https://github.com/josfox-jos/jos
Project-URL: Repository, https://github.com/josfox-jos/jos
Project-URL: Issues, https://github.com/josfox-jos/jos/issues
Project-URL: Specification, https://github.com/josfox-jos/jos-spec
Keywords: jos,.jos,intention,workflow,ai-agents,kernel,ledger,receipts,offline-first,zero-dependencies
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: POSIX
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# jos-core

The reference kernel of the `.jos` 2.1 format, in Python: it validates `.jos` intentions and runs them within their limits, with a receipt per step and a hash-chained ledger per run.

Version 2.1.1 · `.jos` 2.1 · Python 3.10 or later · no dependencies · Apache-2.0

## Install

```
pip install jos-core
```

## Quick start

```
echo '{"jos":{"version":"2.0.0","kind":"atom"},"id":"hello","meta":{"name":"hello","version":"0.1.0"},"intention":{"objective":"Say hello","success_criteria":[{"stdout_contains":"hello"}]},"execution":{"run":["echo","hello"]}}' > hello.jos
jos-core run hello.jos                    # hello, then: jos-core: code 0 art_… run_…
jos-core validate hello.jos --json
jos-core --version                        # jos-core 2.1.1 (.jos 2.1.0), the same line as the JavaScript kernel
```

## As a library

`import jos_core; r = jos_core.run_file('hello.jos')` reads the file once and runs it with `dir` and `source` (its octets); `jos_core.run(doc, cwd=..., dir=..., source=data)` is the same with a document already parsed. A 0.0.7 document sealed by a detached manifest (`security.integrity_ref`) is verified over the octets it was parsed from, so `run()` needs `dir` and `source` for it (else code 5); `verify_legacy_ref(doc, data, dir)` is that check alone.

## Conformance

Same results as the JavaScript kernel `@josfox/jos-core` on every conformance vector: results are compared as JSON values, with minted ids, times and durations normalized (the printed text can differ in member order and number spelling, `5.0` against `5`, never in a value). A number an IEEE 754 double does not keep makes the document invalid in both engines.

## The .jos family

| Package | What it is | Install |
|---|---|---|
| `@josfox/jos-core` | The reference kernel in JavaScript: validates and runs `.jos` documents; zero dependencies | `npm install @josfox/jos-core` |
| `jos-core` (PyPI) | The same kernel in Python, with the same results on every conformance vector | `pip install jos-core` |
| `@josfox/jos` | `jos`, the command line: run, validate, ledger, vault, MCP server | `npm install -g @josfox/jos` |
| `foxjos` | The `jos` command line under its own name, for foxtail authors | `npm install -g foxjos` |
| `@josfox/jos-cli` | `jos-cli`, the operator client for `.jos` instances | `npm install -g @josfox/jos-cli` |
| `josfox` | Where a person starts: `josfox kickoff` | `npm install -g josfox` |
| `josctl` | The control plane of the master plan | `npm install -g josctl` |
| `@josfox/foxctl`, `foxctl` | The services CLI (the unscoped name is the same program) | `npm install -g @josfox/foxctl` |

Every npm package of this release pins `@josfox/jos-core` 2.1.1 exactly.

## Links

- Specification, schemas and conformance kit: https://github.com/josfox-jos/jos-spec
- Repository: https://github.com/josfox-jos/jos
- Issues: https://github.com/josfox-jos/jos/issues

## License

Apache-2.0 ([LICENSE](LICENSE)).

## Sponsor

**.jos is sponsored by JOSFOX and JOSFOX.AI**, who are creating the .jos community. Our purpose: **more wow moments.**
Look soon for your local JOSFOX page in your country for the wow experiences available near you.
https://josfox.ai · https://josfox.cloud

*JOSFOX: more wow moments.*
