namel3ss 0.1.0a9__tar.gz

namel3ss-0.1.0a9/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+No breaking changes without an explicit changelog entry.
+
+## v0.1.0a7
+### Changed
+- Release metadata version bump to 0.1.0a7 (no runtime changes).
+
+## v0.1.0a6
+### Added
+- Package manifest `namel3ss.toml` and lockfile `namel3ss.lock.json`.
+- GitHub-backed package installs into `packages/` with checksum and license verification.
+- `n3 pkg` commands: add/install/plan/tree/why/verify/licenses (+ `--json`).
+- Packages docs and demo example (`docs/packages.md`, `examples/module_imports/`).
+- Python tool venv support with per-app `.venv`, dependency detection, and `n3 deps` commands.
+- Tool traces now include python env metadata and dependency source.
+- Studio Tool Wizard for generating python tool skeletons.
+- Built-in python tool packs (http, datetime, text, file, math) with no extra deps.
+- `n3 doctor` now checks python tool declarations, deps, venv, and lockfile status.
+- Python tool subprocess protocol v1 documentation.
+
+### Changed
+- Module resolution now checks `packages/<name>/` after `modules/<name>/`.
+- Breaking change: removed the old technical tool syntax in favor of English-first tool blocks and calls.
+
+Before:
+```ai
+tool "greeter":
+  kind is "python"
+  entry is "tools.sample_tool:greet"
+  input_schema is json
+  output_schema is json
+
+flow "hello":
+  let result is call tool "greeter" with input: input
+```
+
+After:
+```ai
+tool "greet someone":
+  implemented using python
+
+  input:
+    name is text
+
+  output:
+    message is text
+
+flow "hello":
+  let result is greet someone:
+    name is "Ada"
+```
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+## v0.1.0a5
+### Added
+- Capsules module system with `modules/<name>/capsule.ai`, explicit exports, and `use "<module>" as <alias>` imports.
+- Deterministic module loading with cycle detection.
+- CLI: `n3 <app.ai> graph` and `n3 <app.ai> exports` (plus `--json`).
+- Built-in test runner: `n3 test` with `tests/*_test.ai`.
+- Docs and example project for modules/tests.
+
+### Changed
+- Form/state record paths now namespace qualified record names (modules use `state.<module>.<record>`).
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+## v0.1.0a4
+### Added
+- Decimal literals and arithmetic (+ - * /) with deterministic evaluation.
+- If/else conditionals with `is not`, `is at least`, `is at most` comparisons.
+- Canonical record creation: `create "Record" with <values> as <var>`.
+- New examples and docs for expressions/conditionals (see `examples/demo_order_totals.ai`, `docs/expressions-and-conditionals.md`).
+
+### Changed
+- Numeric engine values use Decimal internally; JSON output preserves decimals without rounding.
+- Lint warns on legacy `save Record` usage (still supported).
+
+### Fixed
+
+### Deprecated
+- Legacy `save Record` (warning only in v0.1.x; use `create` instead).
+
+### Removed
+
+## v0.1.0a1
+### Added
+- PyPI metadata polish (URLs, authors, license), no functional changes.
+
+### Changed
+- Stability: core CLI entrypoints and manifest shape stay stable; breaking changes are documented.
+
+### Fixed
+
+### Deprecated
+
+### Removed
+
+## v0.1.0-alpha
+
+### Added
+- Language core (Phases 1–3): Stable keywords, parser/AST/IR contracts, deterministic defaults.
+- Full-stack UI + actions (Phase 4): Pages, actions, and engine wiring for forms/buttons/tables.
+- AI + memory + tools (Phase 5): AI declarations with memory profiles and tool exposure.
+- Multi-agent workflows (Phase 6): Agent declarations plus sequential/parallel agent execution.
+- CLI, formatter, linter (Phase 7): File-first CLI, formatting rules, linting for grammar/safety.
+- Studio (viewer → interactor → safe edits) (Phase 8): Manifest viewer, action runner, and guarded edits.
+- Templates & scaffolding (Phase 10): `n3 new` with CRUD, AI assistant, and multi-agent templates.
+
+### Changed
+
+### Fixed
+
+### Deprecated
+
+### Removed
+- Added canonical type enforcement: aliases (string/int/bool) are deprecated; formatter rewrites them and lint errors by default. Use text/number/boolean (json if applicable).

namel3ss-0.1.0a9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 namel3ss
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

namel3ss-0.1.0a9/MANIFEST.in

@@ -0,0 +1,4 @@
+include VERSION
+include CHANGELOG.md
+recursive-include src/namel3ss/templates *
+recursive-include src/namel3ss/studio/web *

namel3ss-0.1.0a9/PKG-INFO

@@ -0,0 +1,420 @@
+Metadata-Version: 2.4
+Name: namel3ss
+Version: 0.1.0a9
+Summary: An AI-native programming language with deterministic execution, explainability, and governed memory.
+Author-email: namel3ss <info@namel3ss.com>
+License: MIT License
+        
+        Copyright (c) 2026 namel3ss
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/namel3ss-Ai/namel3ss
+Project-URL: Repository, https://github.com/namel3ss-Ai/namel3ss
+Project-URL: Documentation, https://github.com/namel3ss-Ai/namel3ss/tree/main/docs
+Project-URL: Issues, https://github.com/namel3ss-Ai/namel3ss/issues
+Project-URL: Changelog, https://github.com/namel3ss-Ai/namel3ss/blob/main/CHANGELOG.md
+Keywords: ai,agents,dsl,programming-language,ollama,openai
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Intended Audience :: Developers
+Classifier: Development Status :: 3 - Alpha
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Software Development :: Interpreters
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Provides-Extra: postgres
+Requires-Dist: psycopg[binary]>=3; extra == "postgres"
+Dynamic: license-file
+
+# namel3ss
+Designed to be understood
+
+![status: alpha](https://img.shields.io/badge/status-alpha-blue)
+![license: MIT](https://img.shields.io/badge/license-MIT-green)
+![tests](https://github.com/namel3ss-Ai/namel3ss/actions/workflows/ci.yml/badge.svg)
+
+---
+
+## Why namel3ss exists
+
+Software has changed.
+
+AI is now part of how applications think, decide, and respond.  
+But most programming languages were designed long before that.
+
+So developers add AI with layers of glue like prompts, memory, tools, retries, and guardrails, all scattered across systems. It works.  
+Until it doesn't.  
+And when it fails, no one can clearly see **what happened, or why**.
+
+**namel3ss removes the glue.**
+
+AI, memory, UI, and logic are built into a single, deterministic model so every run can be understood, explained, and trusted.
+
+## What is namel3ss?
+
+namel3ss is an **AI-native programming language**.
+
+It treats AI as a first-class concept, while keeping execution explicit, state visible, and behavior explainable.
+
+One `.ai` file can describe:
+- what the application shows
+- what it does
+- how AI is used
+- what memory is read or written
+- and why each decision happened
+
+Nothing is hidden.
+
+## Design guarantees
+
+namel3ss is built around a few non-negotiable ideas:
+
+- **Deterministic execution**  
+  Every run follows a clear, stable path.
+
+- **Frozen grammar and semantics**  
+  The language grammar is stable and phase-aware (STATIC vs RUNTIME) with identical rules enforced by CLI and Studio.
+
+- **Explicit AI boundary**  
+  AI is never implicit. Every AI call is visible and traced.
+
+- **Explainability by default**  
+  You can always ask: *what happened, and why?*
+
+- **Governed memory**  
+  Memory is explicit, inspectable, and policy-driven, not hidden context.
+
+- **One file, one mental model**  
+  UI, data, logic, tools, and AI live together, so intent stays clear.
+
+- **Frozen UI surface**  
+  The UI DSL is frozen for v0.1.x; changes are additive and documented.
+
+These are not features.  
+They are guarantees.
+
+## Runtime guarantees
+
+namel3ss provides the following guarantees, enforced by code, tests, and governance:
+
+- Deterministic execution with an explicit AI boundary
+- Read-only diagnostics (`n3 status`, `n3 explain`)
+- Safe cleanup of runtime artifacts (`n3 clean`)
+- Bounded, managed runtime artifacts (safe to delete)
+- Governed memory with explicit writes and recall
+- Contract-stable cli, grammar, and explain outputs
+
+These guarantees are enforced and frozen for the v0.1.x series.
+
+## Installation
+
+The recommended way to install `n3` is with `pipx`, which keeps it isolated and globally available:
+
+```bash
+pipx install namel3ss
+```
+
+Or via pip:
+
+```bash
+python -m pip install -U namel3ss
+```
+
+### Verify installation
+
+```bash
+n3 --version
+n3 --help
+```
+
+### Windows users
+If `n3` is not found, your Python `Scripts/` folder may not be in your PATH.
+You can always use the fallback command:
+
+```bash
+python -m namel3ss --help
+```
+
+## Try it in 60 seconds
+
+```bash
+python -m pip install -U namel3ss
+n3 --help
+n3 new demo
+cd demo
+n3 run
+```
+
+### What happens when you run `n3 check`
+- Runs STATIC validation only: grammar, structure, schema, and manifest build.
+- Does not require identity/env vars or runtime state; runtime-only rules become warnings.
+- Mirrors Studio load exactly.
+
+### What happens when you run `n3 run`
+- Executes flows with RUNTIME enforcement: identity/trust, permissions, capability checks, and data existence.
+- Uses the same grammar and manifest you validated with `n3 check`.
+
+First-run defaults:
+- Templates and demos include state defaults or component-provided defaults (chat, charts, cards).
+- No identity or secret configuration is required to load or view the UI.
+
+## Troubleshooting
+
+If `n3` is not recognized:
+
+1. Check installation:
+   ```bash
+   python -m pip show namel3ss
+   ```
+
+2. Check location:
+   ```bash
+   where n3   # Windows
+   which n3   # macOS/Linux
+   ```
+
+3. Fallback command:
+   ```bash
+   python -m namel3ss --help
+   ```
+
+Common PATH locations:
+- Windows: `C:\Users\<User>\AppData\Local\Programs\Python\PythonXY\Scripts` or `%APPDATA%\Python\PythonXY\Scripts`
+- macOS/Linux: `~/.local/bin`
+
+On first run, the browser opens a working application with:
+
+- an orders dataset
+- an AI query flow
+- deterministic execution and traceable decisions
+
+## About ClearOrders
+
+ClearOrders is the reference experience for namel3ss.
+
+It is intentionally not minimal.
+
+It exists to demonstrate:
+
+- AI operating over structured records
+- explicit AI boundaries and deterministic execution
+- explainable "Why?" outputs
+- governed, inspectable memory
+
+Understanding ClearOrders is sufficient to understand the core model of namel3ss.
+
+Grammar and compatibility:
+- Grammar and semantics are frozen and phase-aware; see `docs/language/grammar_contract.md`.
+- Backward-compatibility policy is defined in `docs/language/backward_compatibility.md`.
+- Changes that affect grammar or semantics require an RFC (`docs/language/rfc_process.md`).
+- CI enforces grammar contract tests and STATIC build checks for templates/examples to prevent drift.
+
+## What makes it different
+- One `.ai` file defines data, UI, backend logic, and AI.
+- Deterministic execution environment by default; AI is explicit and traced.
+- Built-in run summary and explanations for flows, tools, and UI.
+- File-first CLI and Studio for inspection and interaction.
+- First-run experience that opens the demo in a browser automatically.
+
+## Build agents you can explain
+- Agent Builder in Studio scaffolds agents from deterministic patterns.
+- Agent Timeline shows memory, tool usage, merges, and handoffs as trace-backed facts.
+- Memory Packs and handoff previews keep agent memory explicit and inspectable.
+- Merge policies make multi-agent outputs predictable and traceable.
+- Tool-call lifecycle events are canonical across providers.
+
+## Evaluate and ship
+- `n3 eval` runs deterministic evaluation suites and emits stable JSON/TXT reports.
+- Eval results are wired into release gates to prevent regressions.
+
+## Beta lock surfaces
+- Agent explain payloads, tool-call lifecycle events, merge lifecycle events, memory pack events, and CLI outputs are contract-stable and enforced by tests.
+
+## Expressions
+Flows support concise, deterministic math and list transforms:
+- `let:` blocks for grouped declarations (multi-line or inline comma entries)
+- `between` / `strictly between` comparisons
+- `**` exponentiation (right-associative; `-2 ** 2` is `-(2 ** 2)`)
+- list aggregations `sum/min/max/mean/median` with strict numeric validation
+- list transforms `map/filter/reduce` with scoped binders
+- `calc:` formula blocks, including `state.<path> = ...` assignments
+
+Example:
+```ai
+spec is "1.0"
+flow "demo":
+  let numbers is list:
+    1
+    2
+    3
+    10
+
+  calc:
+    doubled = map numbers with item as n:
+      n * 2
+    big = filter doubled with item as x:
+      x is greater than 5
+    state.total = reduce big with acc as s and item as v starting 0:
+      s + v
+    state.avg = mean(big)
+    d = 2 ** 3 ** 2
+    ok = state.total is between 0 and 100
+
+  return map:
+    "total" is state.total
+    "avg" is state.avg
+    "d" is d
+    "ok" is ok
+```
+
+## Quickstart (non-demo)
+```bash
+n3 new starter my_app
+cd my_app
+n3 app.ai
+```
+
+Minimal UI example:
+```ai
+page "home":
+  title is "Hello"
+  text is "Welcome"
+```
+
+Optional AI example:
+```ai
+ai "assistant":
+  provider is "mock"
+  model is "mock-model"
+  system_prompt is "You are a concise assistant."
+
+flow "reply":
+  ask ai "assistant" with input: input.message as reply
+  return reply
+```
+
+This is the core idea:  
+intent first, execution second, explanation always.
+
+## Who namel3ss is for
+namel3ss is for:
+- builders exploring AI-native application development
+- developers who care about explainability and trust
+- language and tooling enthusiasts
+- learning, experimentation, and internal tools
+
+namel3ss is not trying to replace Python or JavaScript.  
+It is exploring what comes next.
+
+## Status
+namel3ss is in alpha (v0.1.0a9). It is suitable for learning and experimentation, not production.  
+Expect breaking changes between alpha revisions.
+
+## Start here (learning path)
+- [Quickstart](docs/quickstart.md)
+- [First 5 minutes](docs/first-5-minutes.md)
+- [What you can build today](docs/what-you-can-build-today.md)
+
+## Documentation index
+### Getting started
+- [Learning book](docs/learning-namel3ss.md)
+- [Quickstart](docs/quickstart.md)
+- [First 5 minutes](docs/first-5-minutes.md)
+- [What you can build today](docs/what-you-can-build-today.md)
+- [Examples](examples/)
+- [Demo: CRUD dashboard](docs/examples/demo_crud_dashboard.md)
+- [Demo: onboarding flow](docs/examples/demo_onboarding_flow.md)
+- [Demo: AI assistant over records](docs/examples/demo_ai_assistant_over_records.md)
+- [Documentation directory](docs/)
+
+### UI
+- [UI DSL spec](docs/ui-dsl.md)
+
+### Explainability
+- [Execution how](docs/execution-how.md)
+- [Run outcome](docs/flow-what.md)
+- [Tools with](docs/tools-with.md)
+- [UI see](docs/ui-see.md)
+- [Errors fix](docs/errors-fix.md)
+- [Build exists](docs/build-exists.md)
+- [CLI: exists](docs/cli-exists.md)
+- [CLI: fix](docs/cli-fix.md)
+- [CLI: what](docs/cli-what.md)
+- [CLI: when](docs/cli-when.md)
+- [CLI: with](docs/cli-with.md)
+
+### Tools & packs
+- [Python tools](docs/python-tools.md)
+- [Tool packs](docs/tool-packs.md)
+- [Capabilities](docs/capabilities.md)
+- [Publishing packs](docs/publishing-packs.md)
+- [Registry](docs/registry.md)
+- [Editor](docs/editor.md)
+
+### Deployment & production
+- [Quick deployment guide](docs/quick-deployment-guide.md) - Docker and systemd deployment
+- [Production deployment guide](docs/production-deployment.md) - Comprehensive production setup
+- [Production readiness roadmap](docs/production-readiness-roadmap.md) - Path to v1.0
+- [Targets and promotion](docs/targets-and-promotion.md)
+
+### Trust, memory & governance
+**Memory in one minute:** namel3ss memory is **explicit**, **governed**, and **inspectable**. It records what matters (preferences, decisions, facts, corrections) under clear policies, with deterministic recall and traceable writes, so AI behavior can be reviewed instead of guessed. You can inspect what was recalled or written through Studio and CLI explanations.
+- [Trust and governance](docs/trust-and-governance.md)
+- [Memory overview](docs/memory.md)
+- [Concurrency model](docs/concurrency.md)
+- [AI language definition](docs/ai-language-definition.md)
+
+### Stability & limitations
+- [Stability](docs/stability.md)
+- [Expression surface v1](docs/expression-surface.md)
+- [Spec freeze](docs/spec-freeze.md)
+- [Canonical version map](resources/spec_versions.json)
+- [Beta checklist](docs/beta-checklist.md)
+- [Known limitations](resources/limitations.md)
+- [Changelog](CHANGELOG.md)
+
+## Community & support
+- [Issues](https://github.com/namel3ss-Ai/namel3ss/issues)
+- [Discussions](https://github.com/namel3ss-Ai/namel3ss/discussions/)
+- [Discord](https://discord.gg/x8s6aEwdU)
+- [LinkedIn](https://www.linkedin.com/company/namel3ss/)
+- [Email](mailto:info@namel3ss.com)
+- [Source repository](https://github.com/namel3ss-Ai/namel3ss)
+
+## About the name
+The "3" in namel3ss is intentional.
+
+It reflects a belief:  
+the basics of a programming language should be understandable in minutes, not hours.
+
+For us, "3" is a reminder.  
+If the core ideas of namel3ss cannot be understood in about three minutes, the language, not the developer, has failed.
+
+When that happens, we redesign it.
+
+## Contributing
+Read [CONTRIBUTING.md](CONTRIBUTING.md) and [ECOSYSTEM.md](ECOSYSTEM.md).