penampakan 0.1.0__tar.gz

penampakan-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy --strict src/penampakan
+      - run: pytest -m 'not models and not ocr' --cov=penampakan --cov-fail-under=90
+      - run: python -m build
+      - run: python -m twine check dist/*
+
+  windows-smoke:
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+          cache: pip
+      - run: python -m pip install -e '.[dev]'
+      - run: python -c "import penampakan"
+      - run: pytest -m "not models and not ocr"

penampakan-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.coverage
+.env
+.hypothesis/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+build/
+dist/
+htmlcov/
+*.egg-info/
+*.py[cod]
+!README.md

penampakan-0.1.0/CHANGELOG

@@ -0,0 +1,12 @@
+Penampakan 0.1.0
+Released 2026-08-10
+
+Initial release of bounded visual tool orchestration for text-only language
+models. It includes strict public contracts, safe image normalization,
+deterministic perception routing, evidence-grounded question answering,
+reusable asynchronous and synchronous sessions, optional local model adapters,
+redacted tracing, and experimental evaluation metrics.
+
+Metadata inspection now reuses the loader's canonical image, uses balanced PNG
+compression, and reports reusable-session latency plus executed normalization
+and safety checks in the benchmark.

penampakan-0.1.0/IMPLEMENTATION_SPEC.md

@@ -0,0 +1,51 @@
+# Penampakan implementation specification
+
+Status: proposed v0.1 specification
+
+Last updated: 2026-08-10
+
+Penampakan is a Python library that lets a text-only language model answer
+questions about static images. It does this by translating image evidence into
+typed, attributable text observations and letting the language model request
+additional bounded vision operations when the initial evidence is insufficient.
+
+This document set is normative for the first implementation. Read it in order:
+
+1. [Research and product scope](docs/specs/00-research-and-product.md)
+2. [Architecture](docs/specs/01-architecture.md)
+3. [Public API and data contracts](docs/specs/02-public-api-and-contracts.md)
+4. [Runtime, tools, and backends](docs/specs/03-runtime-tools-and-backends.md)
+5. [Delivery plan and quality gates](docs/specs/04-delivery-and-quality.md)
+
+The words MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY are requirements in the
+sense used by RFC 2119. A coding agent must not silently replace a MUST with a
+different design. If a requirement proves impractical, record the deviation in
+an architecture decision record before implementing it.
+
+## One-paragraph implementation target
+
+Build an async-first, provider-neutral package named `penampakan`. It must load
+and normalize safe raster image inputs, retain immutable original and derived
+image assets, invoke registered vision backends through typed capabilities,
+store every result as a provenance-bearing observation, and run a bounded JSON
+action loop in which a text-only LLM either calls a declared vision tool or
+answers using observation citations. Ship a synchronous facade, deterministic
+fake backends, core Pillow tools, at least one usable caption/detection adapter
+and one OCR adapter, complete contract tests, and examples that work without a
+multimodal LLM.
+
+## Definition of success for v0.1
+
+The release is complete only when all of the following are true:
+
+- A user can call `Penampakan.ask(image, question)` with a text-only LLM and
+  receive a `VisionAnswer` containing inspectable evidence references.
+- A user can call `inspect` without configuring any LLM.
+- Vision capabilities are replaceable independently; the orchestrator never
+  imports a concrete model package.
+- Unsupported or inconclusive perception produces an explicit
+  `insufficient_evidence` result instead of a fabricated answer.
+- Image bytes, OCR text, and prompts are not logged or persisted by default.
+- No LLM-generated Python or shell code is executed in v0.1.
+- Unit, backend-contract, orchestration, security, and end-to-end tests described
+  in the quality spec pass on all supported Python versions.

penampakan-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Penampakan contributors
+
+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.

penampakan-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: penampakan
+Version: 0.1.0
+Summary: Safe visual tool orchestration for text-only language models
+Author: Penampakan contributors
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: <3.14,>=3.10
+Requires-Dist: pillow>=10
+Requires-Dist: pydantic<3,>=2.7
+Requires-Dist: typing-extensions>=4.10; python_version < '3.12'
+Provides-Extra: benchmark
+Requires-Dist: imageio>=2.31; extra == 'benchmark'
+Requires-Dist: matplotlib>=3.8; extra == 'benchmark'
+Requires-Dist: numpy>=1.23; extra == 'benchmark'
+Requires-Dist: opencv-python-headless>=4.8; extra == 'benchmark'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: hypothesis>=6.100; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: twine>=5; extra == 'dev'
+Provides-Extra: ocr
+Requires-Dist: pytesseract>=0.3.10; extra == 'ocr'
+Provides-Extra: transformers
+Requires-Dist: torch>=2.1; extra == 'transformers'
+Requires-Dist: transformers<5,>=4.40; extra == 'transformers'
+Description-Content-Type: text/markdown
+
+# Penampakan
+
+Penampakan is an async-first Python library that lets a text-only language
+model reason about static images. It turns results from replaceable vision
+backends into typed, attributable observations, then runs a bounded tool loop
+that requires the model to cite those observations in its answer.
+
+The package can also be used without a language model for deterministic image
+inspection. Its built-in Pillow backend provides normalized metadata and
+dominant colors; optional adapters add Tesseract OCR and local Transformers
+captioning or detection.
+
+Penampakan is currently alpha software.
+
+## Why Penampakan?
+
+- Provider-neutral protocols for text LLMs and vision backends.
+- Async clients and sessions, plus a blocking facade for synchronous programs.
+- Immutable Pydantic contracts for assets, observations, evidence, and traces.
+- Bounded tool, backend, LLM, image, and timeout budgets.
+- Safe raster normalization with provenance for derived images.
+- Evidence-grounded answers and redacted tracing by default.
+- No generated Python or shell execution.
+
+## Installation
+
+Penampakan requires Python 3.10 through 3.13.
+
+```bash
+python -m pip install penampakan
+```
+
+Optional integrations are installed separately:
+
+```bash
+python -m pip install 'penampakan[ocr]'
+python -m pip install 'penampakan[transformers]'
+```
+
+The OCR extra installs the Python adapter; the Tesseract executable must also
+be available on the system.
+
+## Quick start
+
+Inspect an image without configuring an LLM:
+
+```python
+from penampakan import (
+    ColorsRequest,
+    InspectionOperation,
+    InspectionPlan,
+    MetadataRequest,
+    Penampakan,
+)
+
+plan = InspectionPlan(
+    operations=(
+        InspectionOperation(request=MetadataRequest()),
+        InspectionOperation(request=ColorsRequest(count=5)),
+    ),
+    include_available_overview=False,
+)
+
+with Penampakan() as vision:
+    result = vision.inspect("photo.png", plan)
+
+for observation in result.observations:
+    print(observation.payload)
+```
+
+For evidence-grounded question answering, construct `AsyncPenampakan` or
+`Penampakan` with a `TextLLM` implementation and the vision backends needed for
+the task, then call `ask(image, question)`. `CallableTextLLM` and
+`CallableVisionBackend` are available as adapters for application functions.
+
+Input images may be PNG, JPEG, or WebP paths, encoded bytes, binary streams, or
+Pillow images. Remote URLs are rejected by default. Images are orientation
+corrected, bounded by configurable limits, and normalized to canonical RGB or
+RGBA assets before a backend sees them.
+
+## Benchmark
+
+The benchmark is at
+[`benchmarks/benchmark_metadata.py`](benchmarks/benchmark_metadata.py). It
+compares the latency of an end-to-end Penampakan metadata inspection with
+direct metadata decoding through Pillow, OpenCV, and ImageIO. The fixture is
+generated locally, competitors are run in rotating order over multiple rounds,
+and unavailable optional libraries are clearly reported as skipped. It also
+measures Penampakan's reusable-session workflow and executes representative
+normalization, safety, and attribution checks so the additional work in the
+end-to-end path remains visible.
+
+Install the benchmark dependencies and run it from the repository root:
+
+```bash
+python -m pip install -e '.[benchmark]'
+python benchmarks/benchmark_metadata.py
+```
+
+Use `--help` to change the image size, warmups, iterations, rounds, or output
+format. For example:
+
+```bash
+python benchmarks/benchmark_metadata.py --iterations 50 --rounds 7
+python benchmarks/benchmark_metadata.py --reuse-count 50
+python benchmarks/benchmark_metadata.py --format json
+python benchmarks/benchmark_metadata.py --plot benchmarks/metadata_latency.png
+```
+
+Reference results captured on 10 August 2026 with Python 3.13.15 on x86-64
+WSL2 (Linux 6.18.33.2, glibc 2.43) are shown below. The run used the default
+640x480 RGBA PNG fixture (45,019 encoded bytes), 3 warmups, 20 iterations, and
+5 rounds. The primary table is the one-shot end-to-end comparison.
+
+![Metadata inspection latency benchmark](benchmarks/metadata_latency.png)
+
+| Library | Version | Median (ms) | Min (ms) | Max (ms) | Calls/s | vs fastest |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| Penampakan | 0.1.0 | 18.846 | 18.781 | 19.030 | 53.1 | 6.85x |
+| Pillow (direct) | 12.3.0 | 2.753 | 2.737 | 2.806 | 363.2 | 1.00x |
+| OpenCV | 5.0.0 | 3.237 | 3.129 | 3.461 | 309.0 | 1.18x |
+| ImageIO | 2.37.4 | 4.431 | 4.347 | 4.470 | 225.7 | 1.61x |
+
+The reusable workflow opens and normalizes one image, performs 20 typed
+metadata inspections, and then closes the session. Its median open latency was
+18.114 ms, each warm inspection was 0.494 ms, and close latency was 0.096 ms.
+Including the open and close costs, that is **1.432 ms per inspection
+amortized**, 13.16x faster than Penampakan's one-shot path. This is a
+Penampakan lifecycle measurement, not a ranking against the direct-library
+cases above.
+
+The same run passed six executed contract checks:
+
+- equivalent normalized metadata across PNG, JPEG, and WebP;
+- EXIF orientation before reported dimensions;
+- removal of opaque alpha while preserving real transparency;
+- documented rejection of malformed and animated inputs;
+- remote-source policy and input-byte bounds; and
+- authoritative backend provenance with a completed redacted trace.
+
+This is an overhead benchmark, not a capability or accuracy ranking. The
+Penampakan path performs bounded input handling, orientation and mode
+normalization, canonical encoding and hashing, typed result validation,
+routing, tracing, and session cleanup. The direct alternatives only decode the
+fixture and return equivalent dimensions and alpha metadata. Contract checks
+are reported separately from latency rankings. Compare results on the same
+machine and treat very short runs as smoke tests rather than stable
+measurements.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+ruff check .
+ruff format --check .
+mypy --strict src/penampakan
+pytest -m 'not models and not ocr'
+```
+
+Penampakan is licensed under the MIT License. See [LICENSE](LICENSE).

penampakan-0.1.0/README.md

@@ -0,0 +1,160 @@
+# Penampakan
+
+Penampakan is an async-first Python library that lets a text-only language
+model reason about static images. It turns results from replaceable vision
+backends into typed, attributable observations, then runs a bounded tool loop
+that requires the model to cite those observations in its answer.
+
+The package can also be used without a language model for deterministic image
+inspection. Its built-in Pillow backend provides normalized metadata and
+dominant colors; optional adapters add Tesseract OCR and local Transformers
+captioning or detection.
+
+Penampakan is currently alpha software.
+
+## Why Penampakan?
+
+- Provider-neutral protocols for text LLMs and vision backends.
+- Async clients and sessions, plus a blocking facade for synchronous programs.
+- Immutable Pydantic contracts for assets, observations, evidence, and traces.
+- Bounded tool, backend, LLM, image, and timeout budgets.
+- Safe raster normalization with provenance for derived images.
+- Evidence-grounded answers and redacted tracing by default.
+- No generated Python or shell execution.
+
+## Installation
+
+Penampakan requires Python 3.10 through 3.13.
+
+```bash
+python -m pip install penampakan
+```
+
+Optional integrations are installed separately:
+
+```bash
+python -m pip install 'penampakan[ocr]'
+python -m pip install 'penampakan[transformers]'
+```
+
+The OCR extra installs the Python adapter; the Tesseract executable must also
+be available on the system.
+
+## Quick start
+
+Inspect an image without configuring an LLM:
+
+```python
+from penampakan import (
+    ColorsRequest,
+    InspectionOperation,
+    InspectionPlan,
+    MetadataRequest,
+    Penampakan,
+)
+
+plan = InspectionPlan(
+    operations=(
+        InspectionOperation(request=MetadataRequest()),
+        InspectionOperation(request=ColorsRequest(count=5)),
+    ),
+    include_available_overview=False,
+)
+
+with Penampakan() as vision:
+    result = vision.inspect("photo.png", plan)
+
+for observation in result.observations:
+    print(observation.payload)
+```
+
+For evidence-grounded question answering, construct `AsyncPenampakan` or
+`Penampakan` with a `TextLLM` implementation and the vision backends needed for
+the task, then call `ask(image, question)`. `CallableTextLLM` and
+`CallableVisionBackend` are available as adapters for application functions.
+
+Input images may be PNG, JPEG, or WebP paths, encoded bytes, binary streams, or
+Pillow images. Remote URLs are rejected by default. Images are orientation
+corrected, bounded by configurable limits, and normalized to canonical RGB or
+RGBA assets before a backend sees them.
+
+## Benchmark
+
+The benchmark is at
+[`benchmarks/benchmark_metadata.py`](benchmarks/benchmark_metadata.py). It
+compares the latency of an end-to-end Penampakan metadata inspection with
+direct metadata decoding through Pillow, OpenCV, and ImageIO. The fixture is
+generated locally, competitors are run in rotating order over multiple rounds,
+and unavailable optional libraries are clearly reported as skipped. It also
+measures Penampakan's reusable-session workflow and executes representative
+normalization, safety, and attribution checks so the additional work in the
+end-to-end path remains visible.
+
+Install the benchmark dependencies and run it from the repository root:
+
+```bash
+python -m pip install -e '.[benchmark]'
+python benchmarks/benchmark_metadata.py
+```
+
+Use `--help` to change the image size, warmups, iterations, rounds, or output
+format. For example:
+
+```bash
+python benchmarks/benchmark_metadata.py --iterations 50 --rounds 7
+python benchmarks/benchmark_metadata.py --reuse-count 50
+python benchmarks/benchmark_metadata.py --format json
+python benchmarks/benchmark_metadata.py --plot benchmarks/metadata_latency.png
+```
+
+Reference results captured on 10 August 2026 with Python 3.13.15 on x86-64
+WSL2 (Linux 6.18.33.2, glibc 2.43) are shown below. The run used the default
+640x480 RGBA PNG fixture (45,019 encoded bytes), 3 warmups, 20 iterations, and
+5 rounds. The primary table is the one-shot end-to-end comparison.
+
+![Metadata inspection latency benchmark](benchmarks/metadata_latency.png)
+
+| Library | Version | Median (ms) | Min (ms) | Max (ms) | Calls/s | vs fastest |
+| --- | --- | ---: | ---: | ---: | ---: | ---: |
+| Penampakan | 0.1.0 | 18.846 | 18.781 | 19.030 | 53.1 | 6.85x |
+| Pillow (direct) | 12.3.0 | 2.753 | 2.737 | 2.806 | 363.2 | 1.00x |
+| OpenCV | 5.0.0 | 3.237 | 3.129 | 3.461 | 309.0 | 1.18x |
+| ImageIO | 2.37.4 | 4.431 | 4.347 | 4.470 | 225.7 | 1.61x |
+
+The reusable workflow opens and normalizes one image, performs 20 typed
+metadata inspections, and then closes the session. Its median open latency was
+18.114 ms, each warm inspection was 0.494 ms, and close latency was 0.096 ms.
+Including the open and close costs, that is **1.432 ms per inspection
+amortized**, 13.16x faster than Penampakan's one-shot path. This is a
+Penampakan lifecycle measurement, not a ranking against the direct-library
+cases above.
+
+The same run passed six executed contract checks:
+
+- equivalent normalized metadata across PNG, JPEG, and WebP;
+- EXIF orientation before reported dimensions;
+- removal of opaque alpha while preserving real transparency;
+- documented rejection of malformed and animated inputs;
+- remote-source policy and input-byte bounds; and
+- authoritative backend provenance with a completed redacted trace.
+
+This is an overhead benchmark, not a capability or accuracy ranking. The
+Penampakan path performs bounded input handling, orientation and mode
+normalization, canonical encoding and hashing, typed result validation,
+routing, tracing, and session cleanup. The direct alternatives only decode the
+fixture and return equivalent dimensions and alpha metadata. Contract checks
+are reported separately from latency rankings. Compare results on the same
+machine and treat very short runs as smoke tests rather than stable
+measurements.
+
+## Development
+
+```bash
+python -m pip install -e '.[dev]'
+ruff check .
+ruff format --check .
+mypy --strict src/penampakan
+pytest -m 'not models and not ocr'
+```
+
+Penampakan is licensed under the MIT License. See [LICENSE](LICENSE).