abstractavatar 0.1.0__tar.gz

abstractavatar-0.1.0/ACKNOWLEDGEMENTS.md

@@ -0,0 +1,10 @@
+# Acknowledgements
+
+AbstractAvatar is part of AbstractFramework, created by Laurent-Philippe Albou.
+
+The procedural catalog draws on the AbstractAssistant Apple Watch and iPhone artwork and the
+AbstractTUI shaded activity avatars. Those implementations provide the design vocabulary and
+provenance described in the [catalog](docs/catalog.md).
+
+WebAssembly supplies the portable browser execution format. Python, Rust and platform UI toolkits
+provide the integration surfaces. No machine-learning model is needed to render the catalog.

abstractavatar-0.1.0/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+## [0.1.0] - 2026-11-02
+
+First release of the `abstractavatar` crate on crates.io. AbstractAvatar is a local procedural
+avatar generator: your application supplies a style key, an activity state, time, audio level and
+gaze, and the crate returns composited RGBA pixels. One Rust implementation serves terminal,
+native and browser hosts.
+
+### Added
+
+- A catalog of 44 procedural designs (shaded characters, particle orbs, forms, portraits,
+  machines, nature scenes and a woven orb) with stable style keys, display names, families and
+  design provenance.
+- Seven explicit activity states: ready, thinking, working, listening, speaking, waiting and
+  error. Audio level, eight optional audio bands and gaze add visual input to the chosen state;
+  listening and speaking poses respond to measured loudness.
+- Rust API: `AvatarStyle`, `AvatarPose`, `Gaze`, `Frame::new` for repeated sampling, and
+  `Frame::rgba` for composited straight-alpha RGBA8 through host-owned `Palette` ramps, with
+  bounded pixel footprints and antialiasing. `Frame::sample` returns a single-material sample.
+- Layered material compositing: overlapping material light keeps each color contribution, and
+  shaded surfaces and translucent ribbons composite in the shared rasterizer.
+- `ffi` feature: a C ABI (`avatar.h`) with bounded handles (1..512 pixels, at most 16 live
+  handles), palette, gaze and audio-band setters, and `avatar_render_copy` into caller-owned
+  memory. The same exports build for `wasm32-unknown-unknown` for browser Canvas presenters.
+- `json` feature: the versioned, inert parameter descriptor (`schema/descriptor.schema.json`).
+- Python binding and `python -m abstractavatar` preview command, installed from a source
+  checkout with `python -m pip install .`.
+
+### Compatibility
+
+- Persist style keys. Numeric catalog codes are resolved at runtime and are not preference values.
+- The first six ABI catalog codes (`halo`, `hover`, `vortex`, `eclipse`, `eye`, `rover`) keep
+  their ordering.
+- Rust 1.87 or newer.

abstractavatar-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,8 @@
+# Code of Conduct
+
+Treat contributors and users respectfully. Discuss ideas and evidence, welcome different levels
+of experience, and give actionable feedback. Harassment, threats, discrimination and disclosure
+of another person's private information are unacceptable.
+
+Report conduct concerns privately to contact@abstractframework.ai. Maintainers may moderate or
+remove participation that violates these expectations and will handle reports with discretion.

abstractavatar-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Use Rust 1.87+ and Python 3.10+. Build the library before trying its native integrations:
+
+```sh
+cargo test
+cargo test --all-features
+cargo build --release --features ffi
+python -m pip install .
+```
+
+Keep procedural geometry in the shared Rust implementation. UI-specific clocks, preferences,
+colors, focus and input capture belong in the host. New styles need distinct visual behavior,
+source attribution, valid catalog metadata and examples of all supported activity states.
+
+Preserve existing style keys and the published ABI contract. Add rather than repurpose catalog
+entries. Changes to ownership or frame semantics belong in [architecture decisions](docs/adr/0001-portable-procedural-generation.md).
+
+Document public API changes in [the API reference](docs/api.md) and [changelog](CHANGELOG.md).
+Keep documentation indexes current with `python scripts/docs.py`; `python scripts/docs.py --check`
+checks freshness without writing files.
+
+For raster changes, compare native and WebAssembly output with identical ramps and inputs:
+
+```sh
+rustup target add wasm32-unknown-unknown
+python scripts/build_artifacts.py
+python scripts/check_portability.py --native artifacts/libabstractavatar.so
+```
+
+The comparison uses Node.js and a built native library. On macOS use
+`artifacts/libabstractavatar.dylib`; on Windows use `artifacts/abstractavatar.dll`.
+It exercises every style/state at 64 pixels plus the focused particle, ribbon and shaded-surface
+designs at 32 and 128 pixels, including partial material alpha and eight voice bands.
+Visual review still matters: pixel agreement establishes portability, not design fidelity.
+
+Report security concerns using [SECURITY.md](SECURITY.md).

abstractavatar-0.1.0/Cargo.lock

@@ -0,0 +1,107 @@
+# This file is automatically @generated by Cargo.
+# It is not intended for manual editing.
+version = 4
+
+[[package]]
+name = "abstractavatar"
+version = "0.1.0"
+dependencies = [
+ "serde",
+ "serde_json",
+]
+
+[[package]]
+name = "itoa"
+version = "1.0.18"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
+
+[[package]]
+name = "memchr"
+version = "2.8.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
+
+[[package]]
+name = "proc-macro2"
+version = "1.0.107"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
+dependencies = [
+ "unicode-ident",
+]
+
+[[package]]
+name = "quote"
+version = "1.0.47"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
+dependencies = [
+ "proc-macro2",
+]
+
+[[package]]
+name = "serde"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"
+dependencies = [
+ "serde_core",
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_core"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"
+dependencies = [
+ "serde_derive",
+]
+
+[[package]]
+name = "serde_derive"
+version = "1.0.229"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn",
+]
+
+[[package]]
+name = "serde_json"
+version = "1.0.154"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e7e9cc8b1b85264074fbcc02a88680c4096b1e47df8f739dceb03bf482f04bd6"
+dependencies = [
+ "itoa",
+ "memchr",
+ "serde",
+ "serde_core",
+ "zmij",
+]
+
+[[package]]
+name = "syn"
+version = "3.0.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d78c8dee4c7bf0e14673097256fed6142ce9d3b85a408189d07482442145823b"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "unicode-ident",
+]
+
+[[package]]
+name = "unicode-ident"
+version = "1.0.27"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
+
+[[package]]
+name = "zmij"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"

abstractavatar-0.1.0/Cargo.toml

@@ -0,0 +1,25 @@
+[package]
+name = "abstractavatar"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.87"
+license = "MIT"
+description = "Platform-independent procedural activity avatars with optional native/WebAssembly ABI"
+repository = "https://github.com/lpalbou/AbstractAvatar"
+documentation = "https://docs.rs/abstractavatar"
+readme = "README.md"
+authors = ["Laurent-Philippe Albou"]
+keywords = ["avatar", "procedural", "animation", "webassembly", "rgba"]
+categories = ["graphics", "rendering", "multimedia::images", "wasm"]
+exclude = [".github/", "docs/media/"]
+[lib]
+crate-type = ["rlib", "cdylib"]
+[features]
+default = []
+ffi = []
+json = ["dep:serde", "dep:serde_json"]
+[dependencies]
+serde = { version = "1", features = ["derive"], optional = true }
+serde_json = { version = "1", optional = true }
+[package.metadata.docs.rs]
+all-features = true

abstractavatar-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laurent-Philippe Albou <contact@abstractframework.ai>
+
+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.

abstractavatar-0.1.0/MANIFEST.in

@@ -0,0 +1,12 @@
+include Cargo.toml Cargo.lock LICENSE avatar.h catalog.json
+recursive-include src *.rs
+recursive-include schema *.json
+recursive-include python *.py
+recursive-include scripts *.py *.mjs
+recursive-include tests *.py
+recursive-include docs *.md
+recursive-include docs/media *.png
+recursive-include skills *.md
+include llms.txt llms-full.txt
+include ACKNOWLEDGEMENTS.md CHANGELOG.md CODE_OF_CONDUCT.md CONTRIBUTING.md SECURITY.md
+recursive-exclude python/abstractavatar/_native *

abstractavatar-0.1.0/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: abstractavatar
+Version: 0.1.0
+Summary: Shared procedural avatar generation for native, terminal and web platforms
+Author: Laurent-Philippe Albou
+License-Expression: MIT
+Project-URL: Repository, https://github.com/lpalbou/AbstractAvatar
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# AbstractAvatar
+
+[![crates.io](https://img.shields.io/crates/v/abstractavatar.svg)](https://crates.io/crates/abstractavatar)
+[![docs.rs](https://img.shields.io/docsrs/abstractavatar)](https://docs.rs/abstractavatar)
+[![CI](https://github.com/lpalbou/AbstractAvatar/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lpalbou/AbstractAvatar/actions/workflows/ci.yml)
+
+AbstractAvatar generates procedural avatars from explicit activity state, time, audio level and
+gaze. One Rust implementation supplies terminal, browser and native applications with a common
+catalog and rendering behavior.
+
+Use it for an assistant portrait, an activity indicator or a procedural character that responds
+to your application's state. The host supplies state and presentation; AbstractAvatar generates
+the picture locally.
+
+![Procedural avatar catalog](docs/media/catalog.png)
+
+**What's new in 0.1.0:** the first release of the `abstractavatar` crate. See the
+[changelog](CHANGELOG.md#010---2026-11-02).
+
+## Start with Rust
+
+Add the crate from crates.io (Rust 1.87+):
+
+```sh
+cargo add abstractavatar
+```
+
+```rust
+use abstractavatar::{AvatarPose, AvatarStyle, Frame, Gaze, Palette};
+
+let frame = Frame::new(AvatarStyle::Halo, AvatarPose::Speaking, 0.6, 1.2, Gaze::default());
+let palette: Palette = [[0xffc060ff; 256], [0xff7070ff; 256], [0xd8e0ffff; 256]];
+let rgba = frame.rgba(0.2, -0.1, 2.0 / 128.0, &palette);
+```
+
+Enable the `ffi` feature for the C ABI and WebAssembly exports, and `json` for the versioned
+parameter descriptor.
+
+## Start with Python
+
+Build from the repository with Python 3.10+ and Rust 1.87+:
+
+```sh
+git clone https://github.com/lpalbou/AbstractAvatar.git
+cd AbstractAvatar
+python -m pip install .
+python -m abstractavatar catalog
+python -m abstractavatar render --style halo --state speaking --level 0.6 --size 128 --output avatar.png
+```
+
+The Python distribution includes the compiled native library. A source installation builds it
+with Cargo. See [getting started](docs/getting-started.md) for library use and platform builds.
+
+## Integrate a player
+
+- **Rust:** create a `Frame` and sample composited RGBA through your theme's material ramps.
+- **Browser:** run the bundled WebAssembly generator and present RGBA pixels on Canvas.
+- **Python/native:** request RGBA pixels through the binding or the C interface and present them
+  with your UI toolkit.
+
+Store catalog style identifiers, rather than numeric indices. Supply time explicitly, stop
+animation while hidden, and use a static frame when reduced motion is enabled. Platform adapters
+do not need their own geometry implementations.
+
+The catalog includes shaded characters, particle orbs, forms, portraits, machines, nature scenes
+and a woven orb. [Catalog guidance](docs/catalog.md) explains source variants and stable keys.
+
+## Documentation
+
+[Documentation index](docs/README.md) · [Architecture](docs/architecture.md) ·
+[API](docs/api.md) · [Frame contract](docs/frame-contract.md) · [FAQ](docs/faq.md) ·
+[Troubleshooting](docs/troubleshooting.md) · [Contributing](CONTRIBUTING.md) ·
+[Security](SECURITY.md) · [Changelog](CHANGELOG.md)
+
+## For AI agents
+
+Use the [AbstractAvatar skill](skills/abstractavatar/SKILL.md) for the rendering workflow,
+descriptor constraints and platform integration rules. The [LLM index](llms.txt) maps the public
+documentation.

abstractavatar-0.1.0/README.md

@@ -0,0 +1,79 @@
+# AbstractAvatar
+
+[![crates.io](https://img.shields.io/crates/v/abstractavatar.svg)](https://crates.io/crates/abstractavatar)
+[![docs.rs](https://img.shields.io/docsrs/abstractavatar)](https://docs.rs/abstractavatar)
+[![CI](https://github.com/lpalbou/AbstractAvatar/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/lpalbou/AbstractAvatar/actions/workflows/ci.yml)
+
+AbstractAvatar generates procedural avatars from explicit activity state, time, audio level and
+gaze. One Rust implementation supplies terminal, browser and native applications with a common
+catalog and rendering behavior.
+
+Use it for an assistant portrait, an activity indicator or a procedural character that responds
+to your application's state. The host supplies state and presentation; AbstractAvatar generates
+the picture locally.
+
+![Procedural avatar catalog](docs/media/catalog.png)
+
+**What's new in 0.1.0:** the first release of the `abstractavatar` crate. See the
+[changelog](CHANGELOG.md#010---2026-11-02).
+
+## Start with Rust
+
+Add the crate from crates.io (Rust 1.87+):
+
+```sh
+cargo add abstractavatar
+```
+
+```rust
+use abstractavatar::{AvatarPose, AvatarStyle, Frame, Gaze, Palette};
+
+let frame = Frame::new(AvatarStyle::Halo, AvatarPose::Speaking, 0.6, 1.2, Gaze::default());
+let palette: Palette = [[0xffc060ff; 256], [0xff7070ff; 256], [0xd8e0ffff; 256]];
+let rgba = frame.rgba(0.2, -0.1, 2.0 / 128.0, &palette);
+```
+
+Enable the `ffi` feature for the C ABI and WebAssembly exports, and `json` for the versioned
+parameter descriptor.
+
+## Start with Python
+
+Build from the repository with Python 3.10+ and Rust 1.87+:
+
+```sh
+git clone https://github.com/lpalbou/AbstractAvatar.git
+cd AbstractAvatar
+python -m pip install .
+python -m abstractavatar catalog
+python -m abstractavatar render --style halo --state speaking --level 0.6 --size 128 --output avatar.png
+```
+
+The Python distribution includes the compiled native library. A source installation builds it
+with Cargo. See [getting started](docs/getting-started.md) for library use and platform builds.
+
+## Integrate a player
+
+- **Rust:** create a `Frame` and sample composited RGBA through your theme's material ramps.
+- **Browser:** run the bundled WebAssembly generator and present RGBA pixels on Canvas.
+- **Python/native:** request RGBA pixels through the binding or the C interface and present them
+  with your UI toolkit.
+
+Store catalog style identifiers, rather than numeric indices. Supply time explicitly, stop
+animation while hidden, and use a static frame when reduced motion is enabled. Platform adapters
+do not need their own geometry implementations.
+
+The catalog includes shaded characters, particle orbs, forms, portraits, machines, nature scenes
+and a woven orb. [Catalog guidance](docs/catalog.md) explains source variants and stable keys.
+
+## Documentation
+
+[Documentation index](docs/README.md) · [Architecture](docs/architecture.md) ·
+[API](docs/api.md) · [Frame contract](docs/frame-contract.md) · [FAQ](docs/faq.md) ·
+[Troubleshooting](docs/troubleshooting.md) · [Contributing](CONTRIBUTING.md) ·
+[Security](SECURITY.md) · [Changelog](CHANGELOG.md)
+
+## For AI agents
+
+Use the [AbstractAvatar skill](skills/abstractavatar/SKILL.md) for the rendering workflow,
+descriptor constraints and platform integration rules. The [LLM index](llms.txt) maps the public
+documentation.

abstractavatar-0.1.0/SECURITY.md

@@ -0,0 +1,15 @@
+# Security
+
+Report suspected vulnerabilities privately to contact@abstractframework.ai. Include the affected
+version, platform, input and a minimal reproduction. Avoid posting private application data or
+an uncoordinated exploit in a public issue.
+
+AbstractAvatar renders trusted built-in procedural designs. Descriptors are bounded parameters,
+not scripts or arbitrary plug-ins. Use the bundled native library or WebAssembly artifact from a
+trusted build. Do not load native libraries or WebAssembly supplied by an untrusted descriptor.
+
+Hosts remain responsible for validating incoming application messages, controlling frame cadence,
+and releasing renderer resources. The native API is a trusted in-process FFI boundary; callers
+must obey buffer and synchronization requirements in [the frame contract](docs/frame-contract.md).
+
+See [troubleshooting](docs/troubleshooting.md) for input and resource-limit errors.

abstractavatar-0.1.0/avatar.h

@@ -0,0 +1,41 @@
+#ifndef ABSTRACTAVATAR_H
+#define ABSTRACTAVATAR_H
+#include <stdint.h>
+#include <stddef.h>
+#ifdef __cplusplus
+extern "C" {
+#endif
+/* ABI1. Keys are durable; style indices are resolved from this catalog at runtime.
+ * Fields0..4: key,name,description,watch reference,family. String pointers static.
+ * Pose0..6: Ready,Thinking,Working,Listening,Speaking,Waiting,Error.
+ * Palette material0..2: Warm,Eye,Dim; index0..255; rgba0xRRGGBBAA.
+ * Set all768 shades before draw. Dimensions1..512; at most16 live handles.
+ * Negative results are explicit errors. create returns0 on refusal.
+ * Pixel pointers are borrowed until destroy; copy before another render/destroy.
+ * Native hosts serialize palette/draw and concurrent borrowed-pointer access.
+ */
+uint32_t avatar_abi_version(void);
+uint32_t avatar_style_count(void);
+const uint8_t *avatar_style_field_ptr(uint32_t style,uint32_t field);
+size_t avatar_style_field_len(uint32_t style,uint32_t field);
+uint32_t avatar_create(uint32_t width,uint32_t height);
+int32_t avatar_set_shade(uint32_t handle,uint32_t material,uint32_t index,uint32_t rgba);
+int32_t avatar_set_ground(uint32_t handle,uint32_t rgba);
+/* Optional normalized Ready gaze; other poses ignore it. Host expires activity. */
+int32_t avatar_set_gaze(uint32_t handle,float x,float y);
+/* Eight measured normalized bands; clear restores scalar-level defaults. */
+int32_t avatar_set_bands(uint32_t handle,float b0,float b1,float b2,float b3,float b4,float b5,float b6,float b7);
+int32_t avatar_clear_bands(uint32_t handle);
+int32_t avatar_render(uint32_t handle,uint32_t style,uint32_t pose,float level,float seconds,uint32_t transparent);
+/* Atomic render/copy under the registry lock. Caller owns a writable output
+ * allocation of capacity bytes, disjoint from renderer buffers and other calls.
+ * Needs width*height*4 bytes. -6 means null or insufficient output capacity.
+ */
+int32_t avatar_render_copy(uint32_t handle,uint32_t style,uint32_t pose,float level,float seconds,uint32_t transparent,uint8_t *output,size_t capacity);
+const uint8_t *avatar_pixels(uint32_t handle);
+size_t avatar_pixels_len(uint32_t handle);
+int32_t avatar_destroy(uint32_t handle);
+#ifdef __cplusplus
+}
+#endif
+#endif