perceptron 0.1.0__tar.gz

perceptron-0.1.0/HISTORY.md

@@ -0,0 +1,10 @@
+Changelog
+=========
+
+0.1.0 (2025-09-17)
+------------------
+
+- Initial public scaffolding of the Perceptron SDK.
+- CLI entry point `perceptron` with Typer.
+- Core DSL, pointing utilities, and high-level helpers.
+

perceptron-0.1.0/LICENSE

@@ -0,0 +1,80 @@
+# Perceptron, Inc. Non-Production License 
+
+## 1. Scope and acceptance
+
+**1.1. Scope of the Agreement.**
+This Agreement applies to any use, modification, or Distribution of any Perceptron Model by You, regardless of the source You obtained a copy of such Perceptron Model. 
+
+**1.2. Acceptance.** By accessing, using, modifying, Distributing a Perceptron Model, or by creating, using or distributing a Derivative of the Perceptron Model, You agree to be bound by this Agreement. 
+
+**1.3. Acceptance on behalf of a third-party.** If You accept this Agreement on behalf of Your employer or another person or entity, You warrant and represent that You have the authority to act and accept this Agreement on their behalf. In such a case, the word “You” in this Agreement will refer to Your employer or such other person or entity.
+
+## 2. License 
+**2.1. Grant of rights.** Subject to Section 3 below, Perceptron, Inc. hereby grants You a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable, limited license to use, copy, modify, and Distribute under the conditions provided in Section 2.2 below, the Perceptron Model and any Derivatives made by or for Perceptron, Inc. and to create Derivatives of the Perceptron Model. 
+
+**2.2. Distribution of Perceptron Model and Derivatives made by or for Perceptron, Inc..** Subject to Section 3 below, You may Distribute copies of the Perceptron Model and/or Derivatives made by or for Perceptron, Inc., under the following conditions: 
+- You must make available a copy of this Agreement to third-party recipients of the Perceptron Models and/or Derivatives made by or for Perceptron, Inc. you Distribute, it being specified that any rights to use the Perceptron Models and/or Derivatives made by or for Perceptron, Inc. shall be directly granted by Perceptron, Inc. to said third-party recipients pursuant to the Perceptron, Inc. Non-Production License agreement executed between these parties;  
+- You must retain in all copies of the Perceptron Models the following attribution notice within a “Notice” text file distributed as part of such copies: “Licensed by Perceptron, Inc. under the Perceptron, Inc. Non-Production License”.  
+
+**2.3. Distribution of Derivatives made by or for You.** Subject to Section 3 below, You may Distribute any Derivatives made by or for You under additional or different terms and conditions, provided that:
+- In any event, the use and modification of Perceptron Model and/or Derivatives made by or for Perceptron, Inc. shall remain governed by the terms and conditions of this Agreement;
+- You include in any such Derivatives made by or for You prominent notices stating that You modified the concerned Perceptron Model; and
+- Any terms and conditions You impose on any third-party recipients relating to Derivatives made by or for You shall neither limit such third-party recipients’ use of the Perceptron Model or any Derivatives made by or for Perceptron, Inc. in accordance with the Perceptron, Inc. Non-Production License nor conflict with any of its terms and conditions.
+
+## 3. Limitations
+**3.1. Misrepresentation.** You must not misrepresent or imply, through any means, that the Derivatives made by or for You and/or any modified version of the Perceptron Model You Distribute under your name and responsibility is an official product of Perceptron, Inc. or has been endorsed, approved or validated by Perceptron, Inc., unless You are authorized by Us to do so in writing. 
+
+**3.2. Usage Limitation**
+- You shall only use the Perceptron Models and Derivatives (whether or not created by Perceptron, Inc.) for testing, research, Personal, or evaluation purposes in Non-Production Environments; 
+- Subject to the foregoing, You shall not supply the Perceptron Models or Derivatives in the course of a commercial activity, whether in return for payment or free of charge, in any medium or form, including but not limited to through a hosted or managed service (e.g. SaaS, cloud instances, etc.), or behind a software layer.
+ 
+**3.3. Usage not permitted under this Agreement.** If You want to use a Perceptron Model or a Derivative for any purpose that is not expressly authorized under this Agreement, You must request a license from Perceptron, Inc., which Perceptron, Inc. may grant to You in Perceptron, Inc.’s sole discretion. Please contact Perceptron, Inc. at the following e-mail address if You want to discuss such a license: sales@perceptron.inc
+
+## 4. Intellectual Property
+**4.1. Trademarks.** No trademark licenses are granted under this Agreement, and in connection with the Perceptron Models, You may not use any name or mark owned by or associated with Perceptron, Inc. or any of its affiliates, except (i) as required for reasonable and customary use in describing and Distributing the Perceptron Models and Derivatives made by or for Perceptron, Inc. and (ii) for attribution purposes as required by this Agreement.
+
+**4.2. Outputs.** We claim no ownership rights in and to the Outputs. You are solely responsible for the Outputs You generate and their subsequent uses in accordance with this Agreement.
+
+**4.3. Derivatives.** By entering into this Agreement, You accept that any Derivatives that You may create or that may be created for You shall be subject to the restrictions set out in Section 3 of this Agreement.  
+
+# 5. Liability
+**5.1. Limitation of liability.** In no event, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall Perceptron, Inc. be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this Agreement or out of the use or inability to use the Perceptron Models and Derivatives (including but not limited to damages for loss of data, loss of goodwill, loss of expected profit or savings, work stoppage, computer failure or malfunction, or any damage caused by malware or security breaches), even if  Perceptron, Inc. has been advised of the possibility of such damages. 
+
+**5.2. Indemnification.** You agree to indemnify and hold harmless Perceptron, Inc. from and against any claims, damages, or losses arising out of or related to Your use or Distribution of the Perceptron Models and Derivatives.
+
+## 6. Warranty
+**6.1. Disclaimer.** Unless required by applicable law or agreed to in writing, Perceptron, Inc. provides the Perceptron Models and Derivatives on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. Perceptron, Inc. does not represent nor warrant that the Perceptron Models and Derivatives will be error-free, meet Your or any third party’s requirements, be secure or will allow You or any third party to achieve any kind of result or generate any kind of content. You are solely responsible for determining the appropriateness of using or Distributing the Perceptron Models and Derivatives and assume any risks associated with Your exercise of rights under this Agreement.
+
+# 7. Termination
+**7.1. Term.** This Agreement is effective as of the date of your acceptance of this Agreement or access to the concerned Perceptron Models or Derivatives and will continue until terminated in accordance with the following terms. 
+
+**7.2. Termination.** Perceptron, Inc. may terminate this Agreement at any time if You are in breach of this Agreement. Upon termination of this Agreement, You must cease to use all Perceptron Models and Derivatives and shall permanently delete any copy thereof. Sections 5, 6, 7 and 8 shall survive the termination of this Agreement. 
+
+**7.3. Litigation.** If You initiate any legal action or proceedings against Us or any other entity (including a cross-claim or counterclaim in a lawsuit), alleging that the Model or a Derivative, or any part thereof, infringe upon intellectual property or other rights owned or licensable by You, then any licenses granted to You under this Agreement will immediately terminate as of the date such legal action or claim is filed or initiated.
+
+# 8. General provisions
+8.1. Governing Law. This Agreement will be governed by and construed in accordance with the laws of the State of Washington, without regard to its conflict of law principles.
+
+8.2. Jurisdiction. The state and federal courts located in King County, Washington shall have exclusive jurisdiction over any dispute arising out of or relating to this Agreement, and You and We consent to personal jurisdiction and venue in such courts.
+
+**8.3. Severability.** If any provision of this Agreement is held to be invalid, illegal or unenforceable, the remaining provisions shall be unaffected thereby and remain valid as if such provision had not been set forth herein.
+
+# 9. Definitions 
+**“Agreement”**: means this Perceptron, Inc. Non-Production License agreement governing the access, use, and Distribution of the Perceptron Models and Derivatives. 
+
+**“Derivative”**: means any (i) modified version of the Perceptron Model (including but not limited to any customized or fine-tuned version thereof), (ii) work based on the Perceptron Model, or (iii) any other derivative work thereof. For the avoidance of doubt, Outputs are not considered as Derivatives under this Agreement. 
+
+**“Distribution”**, **“Distributing”**, **“Distribute”** or **“Distributed”**: means providing or making available, by any means, a copy of the Perceptron Models and/or the Derivatives as the case may be, subject to Section 3 of this Agreement. 
+
+**“Perceptron, Inc.”**, **“We”** or **“Us”**: means Perceptron, Inc., a Delaware corporation with its principal place of business at 10900 NE 8th St Suite 613, Bellevue, WA 98004.
+
+**“Perceptron Model”**: means the foundational large language model(s), and its elements which include algorithms, software, instructed checkpoints, parameters, source code (inference code, evaluation code and, if applicable, fine-tuning code) and any other elements associated thereto made available by Perceptron, Inc. under this Agreement, including, if any, the technical documentation, manuals and instructions for the use and operation thereof. 
+
+**“Non-Production Environment”**: means any setting, use case, or application of the Perceptron Models or Derivatives that expressly excludes live, real-world conditions, commercial operations, revenue-generating activities, or direct interactions with or impacts on end users (such as, for instance, Your employees or customers). Non-Production Environment may include, but is not limited to, any setting, use case, or application for research, development, testing, quality assurance, training, internal evaluation (other than any internal usage by employees in the context of the company’s business activities), and demonstration purposes. 
+
+**“Outputs”**: means any content generated by the operation of the Perceptron Models or the Derivatives from a prompt (i.e., text instructions) provided by users. For the avoidance of doubt, Outputs do not include any components of a Perceptron Models, such as any fine-tuned versions of the Perceptron Models, the weights, or parameters. 
+
+**“Personal”**: means any use of a Perceptron Model or a Derivative that is (i) solely for personal, non-profit and non-commercial purposes and (ii) not directly or indirectly connected to any commercial activities, business operations, or employment responsibilities. For illustration purposes, Personal use of a Model or a Derivative does not include any usage by individuals employed in companies in the context of their daily tasks, any activity that is intended to generate revenue, or that is performed on behalf of a commercial entity. 
+
+**“You”**: means the individual or entity entering into this Agreement with Perceptron, Inc..
+

perceptron-0.1.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include README.md
+include LICENSE
+include HISTORY.md

perceptron-0.1.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.4
+Name: perceptron
+Version: 0.1.0
+Summary: Perceptron multimodal SDK
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.9.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: httpx>=0.26.0
+Requires-Dist: shellingham>=1.5.0
+Requires-Dist: colorama>=0.4.6
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pre-commit>=3.5; extra == "dev"
+Requires-Dist: ruff==0.13.0; extra == "dev"
+Requires-Dist: ty==0.0.1-alpha.20; extra == "dev"
+Provides-Extra: torch
+Requires-Dist: torch>=2.0; extra == "torch"
+Dynamic: license-file
+
+# Perceptron SDK
+
+Python SDK and CLI for perceptive-language models. The SDK is provider-agnostic and lets you compose visual + language tasks, run them locally for inspection, or execute them via a configured provider. Choose a provider and optional model per call; keep your application code stable across model updates.
+
+---
+
+## Installation
+Perceptron currently ships as a source package (the `perceptron` project on PyPI is unrelated). Install directly from this repository.
+
+- Prerequisites: Python 3.10+, `pip` 23+ (or [`uv`](https://github.com/astral-sh/uv))
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install -e .
+
+# Optional extras
+python -m pip install -e .[torch]    # TensorStream helpers (requires PyTorch)
+python -m pip install -e .[dev]      # Dev tooling
+```
+
+Using `uv`:
+```bash
+uv pip install --editable .
+uv pip install --editable .[torch]
+```
+
+The CLI entry point `perceptron` is available after install.
+
+---
+
+## Configuration
+Set credentials and defaults via environment, programmatically, or the CLI. The SDK ships with a `fal` provider; you can add others by extending `perceptron.client._PROVIDER_CONFIG`.
+
+- `PERCEPTRON_PROVIDER`: provider identifier (default `fal`)
+- `PERCEPTRON_API_KEY`: API key for the selected provider
+- `PERCEPTRON_BASE_URL`: override provider base URL when needed
+- `FAL_KEY`: alternative env var used when `provider=fal`
+
+Programmatic configuration:
+```python
+from perceptron import configure, config
+
+configure(provider="fal", api_key="sk_live_...", base_url="https://api.example/v1")
+
+with config(max_tokens=512):
+    ...  # temporary overrides inside the context
+```
+
+CLI helper:
+```bash
+perceptron config --provider fal --api-key sk_live_...
+```
+
+No credentials? Helpers return compile-only payloads so you can inspect tasks without sending requests.
+
+---
+
+## Python Quickstart
+```python
+from perceptron import caption, detect
+
+# Caption an image (provider default model)
+result = caption("/path/to/image.png", style="concise")
+print(result.text)
+
+# Stream grounded detections; optionally select a specific model
+for event in detect("local.png", classes=["person", "forklift"], model="perceptron", stream=True):
+    if event["type"] == "text.delta":
+        print("chunk", event["chunk"])
+    elif event["type"] == "points.delta":
+        print("bbox", event["points"])
+    elif event["type"] == "final":
+        print("final", event["result"]["points"])
+```
+
+### Few-shot detection from COCO
+```python
+from perceptron import detect_from_coco
+
+runs = detect_from_coco(
+    "/datasets/demo",
+    split="train",
+    shots=4,                 # build balanced in-context examples automatically
+    classes=["defect", "ok"],
+)
+
+for sample in runs:
+    print(sample.image_path.name)
+    for box in sample.result.points or []:
+        print(" -", box.mention, box)
+```
+
+---
+
+## CLI Usage
+The CLI mirrors the high-level helpers and supports directory batching (JSON summaries written alongside input folders).
+
+```bash
+# Generate captions
+perceptron caption image.jpg
+perceptron caption ./images --style detailed
+
+# OCR with a custom prompt
+perceptron ocr schematic.png --prompt "Extract component labels"
+
+# Batched detection (writes detections.json)
+perceptron detect ./frames --classes defect,warning
+
+# Grounded question answering
+perceptron question image.jpg "What stands out?" --expects box --format json
+```
+
+Directory mode disables streaming and logs raw responses, plus per-file validation issues.
+
+---
+
+## High-Level APIs
+- `caption(image, *, style="concise", stream=False, **kwargs)`
+- `ocr(image, *, prompt=None, stream=False, **kwargs)`
+- `detect(image, *, classes=None, examples=None, stream=False, **kwargs)`
+- `detect_from_coco(dataset_dir, *, split=None, classes=None, shots=0, limit=None, **kwargs)`
+
+Notes
+- Pass `model="..."`, `provider="..."`, `max_tokens=...`, etc., through `**kwargs` on any helper.
+- `detect_from_coco` discovers annotations, constructs balanced examples when `shots > 0`, and returns `CocoDetectResult` objects.
+- For advanced workflows, build tasks with the typed DSL (`text`, `system`, `image`, `point`, `box`, `polygon`, `collection`) and decorate with `@perceive` / `@async_perceive`. Use the inspector attached to decorated functions to view compiled payloads without executing.
+
+---
+
+## Troubleshooting
+| Symptom | Likely Cause | Resolution |
+| --- | --- | --- |
+| Compile-only result (no text) | Missing provider credentials | Export `FAL_KEY` / `PERCEPTRON_API_KEY` or call `configure(...)` |
+| `stream_buffer_overflow` warning | Long streaming responses exceeded buffer | Increase `max_buffer_bytes` via `configure` |
+| Empty JSON output in directory mode | No supported image extensions | Ensure files end with `.jpg`, `.png`, `.webp`, `.gif`, `.bmp`, `.tif`, `.tiff`, `.heic`, or `.heif` |
+| Bounding-box bounds errors | Inconsistent coordinates or missing `image=` anchors | Validate input annotations and ensure images are attached |
+
+---
+
+## Development
+- Install tooling: `python -m pip install -e .[dev]` (or `uv pip install --editable .[dev]`)
+- Enable git hooks: `pre-commit install`
+- Run all checks: `pre-commit run --all-files`
+
+Repository layout
+- `src/perceptron` – core SDK and DSL
+- `examples` – runnable usage samples
+- `tests` – high-level API and DSL tests
+
+---
+
+## Releases
+- Publishing is automated: pushing a change to `HISTORY.md` on `main` builds and uploads to PyPI.
+- Before updating `HISTORY.md`, bump the version in both `pyproject.toml` and `src/perceptron/__init__.py` (they must match).
+- Configure the GitHub secret `PYPI_API_TOKEN` with your PyPI token (scoped to the project) to enable publishing.
+
+Manual run: you can also trigger the workflow via the “Run workflow” button in GitHub Actions.
+
+If a version was already uploaded, the workflow skips re-uploading that same version.
+
+---
+
+## Contacts & Support
+- Technical: [support@perceptron.inc](mailto:support@perceptron.inc)
+- Commercial: [sales@perceptron.inc](mailto:sales@perceptron.inc)
+- Careers: [join-us@perceptron.inc](mailto:join-us@perceptron.inc)

perceptron-0.1.0/README.md

@@ -0,0 +1,168 @@
+# Perceptron SDK
+
+Python SDK and CLI for perceptive-language models. The SDK is provider-agnostic and lets you compose visual + language tasks, run them locally for inspection, or execute them via a configured provider. Choose a provider and optional model per call; keep your application code stable across model updates.
+
+---
+
+## Installation
+Perceptron currently ships as a source package (the `perceptron` project on PyPI is unrelated). Install directly from this repository.
+
+- Prerequisites: Python 3.10+, `pip` 23+ (or [`uv`](https://github.com/astral-sh/uv))
+
+```bash
+python -m venv .venv
+source .venv/bin/activate        # Windows: .venv\Scripts\activate
+python -m pip install --upgrade pip setuptools wheel
+python -m pip install -e .
+
+# Optional extras
+python -m pip install -e .[torch]    # TensorStream helpers (requires PyTorch)
+python -m pip install -e .[dev]      # Dev tooling
+```
+
+Using `uv`:
+```bash
+uv pip install --editable .
+uv pip install --editable .[torch]
+```
+
+The CLI entry point `perceptron` is available after install.
+
+---
+
+## Configuration
+Set credentials and defaults via environment, programmatically, or the CLI. The SDK ships with a `fal` provider; you can add others by extending `perceptron.client._PROVIDER_CONFIG`.
+
+- `PERCEPTRON_PROVIDER`: provider identifier (default `fal`)
+- `PERCEPTRON_API_KEY`: API key for the selected provider
+- `PERCEPTRON_BASE_URL`: override provider base URL when needed
+- `FAL_KEY`: alternative env var used when `provider=fal`
+
+Programmatic configuration:
+```python
+from perceptron import configure, config
+
+configure(provider="fal", api_key="sk_live_...", base_url="https://api.example/v1")
+
+with config(max_tokens=512):
+    ...  # temporary overrides inside the context
+```
+
+CLI helper:
+```bash
+perceptron config --provider fal --api-key sk_live_...
+```
+
+No credentials? Helpers return compile-only payloads so you can inspect tasks without sending requests.
+
+---
+
+## Python Quickstart
+```python
+from perceptron import caption, detect
+
+# Caption an image (provider default model)
+result = caption("/path/to/image.png", style="concise")
+print(result.text)
+
+# Stream grounded detections; optionally select a specific model
+for event in detect("local.png", classes=["person", "forklift"], model="perceptron", stream=True):
+    if event["type"] == "text.delta":
+        print("chunk", event["chunk"])
+    elif event["type"] == "points.delta":
+        print("bbox", event["points"])
+    elif event["type"] == "final":
+        print("final", event["result"]["points"])
+```
+
+### Few-shot detection from COCO
+```python
+from perceptron import detect_from_coco
+
+runs = detect_from_coco(
+    "/datasets/demo",
+    split="train",
+    shots=4,                 # build balanced in-context examples automatically
+    classes=["defect", "ok"],
+)
+
+for sample in runs:
+    print(sample.image_path.name)
+    for box in sample.result.points or []:
+        print(" -", box.mention, box)
+```
+
+---
+
+## CLI Usage
+The CLI mirrors the high-level helpers and supports directory batching (JSON summaries written alongside input folders).
+
+```bash
+# Generate captions
+perceptron caption image.jpg
+perceptron caption ./images --style detailed
+
+# OCR with a custom prompt
+perceptron ocr schematic.png --prompt "Extract component labels"
+
+# Batched detection (writes detections.json)
+perceptron detect ./frames --classes defect,warning
+
+# Grounded question answering
+perceptron question image.jpg "What stands out?" --expects box --format json
+```
+
+Directory mode disables streaming and logs raw responses, plus per-file validation issues.
+
+---
+
+## High-Level APIs
+- `caption(image, *, style="concise", stream=False, **kwargs)`
+- `ocr(image, *, prompt=None, stream=False, **kwargs)`
+- `detect(image, *, classes=None, examples=None, stream=False, **kwargs)`
+- `detect_from_coco(dataset_dir, *, split=None, classes=None, shots=0, limit=None, **kwargs)`
+
+Notes
+- Pass `model="..."`, `provider="..."`, `max_tokens=...`, etc., through `**kwargs` on any helper.
+- `detect_from_coco` discovers annotations, constructs balanced examples when `shots > 0`, and returns `CocoDetectResult` objects.
+- For advanced workflows, build tasks with the typed DSL (`text`, `system`, `image`, `point`, `box`, `polygon`, `collection`) and decorate with `@perceive` / `@async_perceive`. Use the inspector attached to decorated functions to view compiled payloads without executing.
+
+---
+
+## Troubleshooting
+| Symptom | Likely Cause | Resolution |
+| --- | --- | --- |
+| Compile-only result (no text) | Missing provider credentials | Export `FAL_KEY` / `PERCEPTRON_API_KEY` or call `configure(...)` |
+| `stream_buffer_overflow` warning | Long streaming responses exceeded buffer | Increase `max_buffer_bytes` via `configure` |
+| Empty JSON output in directory mode | No supported image extensions | Ensure files end with `.jpg`, `.png`, `.webp`, `.gif`, `.bmp`, `.tif`, `.tiff`, `.heic`, or `.heif` |
+| Bounding-box bounds errors | Inconsistent coordinates or missing `image=` anchors | Validate input annotations and ensure images are attached |
+
+---
+
+## Development
+- Install tooling: `python -m pip install -e .[dev]` (or `uv pip install --editable .[dev]`)
+- Enable git hooks: `pre-commit install`
+- Run all checks: `pre-commit run --all-files`
+
+Repository layout
+- `src/perceptron` – core SDK and DSL
+- `examples` – runnable usage samples
+- `tests` – high-level API and DSL tests
+
+---
+
+## Releases
+- Publishing is automated: pushing a change to `HISTORY.md` on `main` builds and uploads to PyPI.
+- Before updating `HISTORY.md`, bump the version in both `pyproject.toml` and `src/perceptron/__init__.py` (they must match).
+- Configure the GitHub secret `PYPI_API_TOKEN` with your PyPI token (scoped to the project) to enable publishing.
+
+Manual run: you can also trigger the workflow via the “Run workflow” button in GitHub Actions.
+
+If a version was already uploaded, the workflow skips re-uploading that same version.
+
+---
+
+## Contacts & Support
+- Technical: [support@perceptron.inc](mailto:support@perceptron.inc)
+- Commercial: [sales@perceptron.inc](mailto:sales@perceptron.inc)
+- Careers: [join-us@perceptron.inc](mailto:join-us@perceptron.inc)

perceptron-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "perceptron"
+version = "0.1.0"
+description = "Perceptron multimodal SDK"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31.0",
+    "rich>=13",
+    "typer>=0.9.0",
+    "Pillow>=9.0.0",
+    "numpy>=1.24",
+    "httpx>=0.26.0",
+    "shellingham>=1.5.0",
+    "colorama>=0.4.6",
+]
+
+[project.scripts]
+perceptron = "perceptron.cli:app"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pre-commit>=3.5",
+    "ruff==0.13.0",
+    "ty==0.0.1-alpha.20",
+]
+torch = [
+    "torch>=2.0",
+]
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["perceptron*"]

perceptron-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

perceptron-0.1.0/src/perceptron/__init__.py

@@ -0,0 +1,108 @@
+"""
+perceptron – Python SDK (v0.1 scaffolding)
+
+Public surface (subject to refinement):
+- DSL: perceive (decorator), text, system, agent, image, point, box, polygon, block
+- Pointing: PointParser, parse_text, extract_points, strip_tags
+- Data constructors for annotations/examples: pt, bbox, poly
+- Config: configure, config (context manager), settings
+
+This initial scaffold focuses on the compile/runtime pieces that do not require
+network access. Transport and streaming are added in later phases.
+"""
+
+__version__ = "0.1.0"
+
+from .config import configure, config, settings
+from .client import Client, AsyncClient
+from .errors import (
+    SDKError,
+    TransportError,
+    TimeoutError,
+    AuthError,
+    RateLimitError,
+    ServerError,
+    BadRequestError,
+    ExpectationError,
+    AnchorError,
+)
+from .pointing.types import (
+    SinglePoint,
+    BoundingBox,
+    Polygon,
+    Collection,
+    pt,
+    bbox,
+    poly,
+    collection,
+)
+from .pointing.parser import (
+    PointParser,
+    ReasoningExtraction,
+    ReasoningStreamCleaner,
+    extract_points,
+    extract_reasoning,
+    parse_text,
+    strip_tags,
+)
+from .dsl.nodes import text, system, agent, image, point, box, polygon, block
+from .dsl.perceive import perceive, async_perceive, inspect_task, PerceiveResult
+from .annotations import annotate_image
+from .highlevel import caption, ocr, detect, detect_from_coco, question
+
+__all__ = [
+    # Config
+    "configure",
+    "config",
+    "settings",
+    "Client",
+    "AsyncClient",
+    # Errors
+    "SDKError",
+    "TransportError",
+    "TimeoutError",
+    "AuthError",
+    "RateLimitError",
+    "ServerError",
+    "BadRequestError",
+    "ExpectationError",
+    "AnchorError",
+    # Pointing types & constructors
+    "SinglePoint",
+    "BoundingBox",
+    "Polygon",
+    "Collection",
+    "pt",
+    "bbox",
+    "poly",
+    "collection",
+    # Parser & helpers
+    "PointParser",
+    "ReasoningExtraction",
+    "ReasoningStreamCleaner",
+    "parse_text",
+    "extract_points",
+    "extract_reasoning",
+    "strip_tags",
+    # DSL nodes & decorator
+    "text",
+    "system",
+    "agent",
+    "image",
+    "point",
+    "box",
+    "polygon",
+    "block",
+    "perceive",
+    "async_perceive",
+    "inspect_task",
+    "PerceiveResult",
+    # High-level helpers
+    "annotate_image",
+    "caption",
+    "ocr",
+    "detect",
+    "question",
+    "detect_from_coco",
+    "__version__",
+]