gigai 0.1.2__tar.gz

gigai-0.1.2/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) 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. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

gigai-0.1.2/MANIFEST.in

@@ -0,0 +1,4 @@
+# Repository tests depend on research evidence and scenario support that are
+# intentionally not part of the source distribution. Do not publish a partial,
+# non-runnable test tree.
+prune tests

gigai-0.1.2/PKG-INFO

@@ -0,0 +1,337 @@
+Metadata-Version: 2.4
+Name: gigai
+Version: 0.1.2
+Summary: Contract-first foundations for a local, user-controlled agent runtime
+License-Expression: Apache-2.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: httpx>=0.27
+Requires-Dist: jsonschema>=4.23
+Requires-Dist: referencing>=0.36
+Provides-Extra: test
+Requires-Dist: pydantic>=2.10; extra == "test"
+Requires-Dist: pytest>=8.3; extra == "test"
+Dynamic: license-file
+
+# GigAI
+
+GigAI is a contract-first exploration of a local, user-controlled runtime for
+turning goals into reviewable, finite execution graphs.
+
+> **Status: pre-alpha contracts and executable research.** The installed
+> distribution implements local `setup`, offline `doctor`, idempotent target
+> `init`, the offline proposal lifecycle (`create`, `feedback`, `revise`,
+> `approve`, and `reject`), and read/open operations over private workpads.
+> It does not run a scheduler or provide a production execution runtime.
+> The package also exposes versioned pre-release serialized contracts and
+> canonical identity primitives. Their immutable release regime begins at
+> GigAI's deliberately declared first public release.
+> Commands beyond the implemented surface remain planned interfaces, not
+> product behavior.
+
+## Why this exists
+
+Agent systems often blur three different decisions: what should happen, who
+approved it, and what is authorized to execute. GigAI keeps them separate:
+
+~~~text
+create or improve -> non-executable proposal
+operator approval -> immutable Gig version
+run               -> authority for one execution
+~~~
+
+A Gig is a finite, user-owned Goal Graph. Its private workpad is authoritative;
+indexes are rebuildable; provider calls are explicit exposure; and imported user
+content is hashed as exact bytes rather than silently normalized.
+
+## What is implemented
+
+- Eight versioned JSON Schema Draft 2020-12 contracts.
+- One production implementation of restricted canonical JSON, owned-text
+  bytes, exact imported-byte digests, prefixed UUIDv4 IDs, and explicit version
+  selection.
+- One installed `gigai` command exposing truthful package help and version,
+  idempotent local setup, structured offline diagnostics, target binding, the
+  non-executable proposal lifecycle, and offline read/open operations.
+- A strict versioned `config.toml` containing structured editor argv,
+  credential references rather than values, one deterministic offline
+  endpoint and target, one default profile, and the authoritative workpad
+  mount.
+- An immutable content-addressed standard pack and fixture-backed offline
+  adapter. Setup and doctor prove atomic replacement and real two-process
+  exclusion on the configured mount without network or token use.
+- A strict path-free `.gigai/project.toml` binding for Git targets, one
+  idempotent `/.gigai/` local exclude entry, and a versioned private
+  `registry.sqlite` that owns canonical target and workpad locators. The exact
+  v1 registry migrates transactionally to v2 after retaining a private,
+  validated v1 backup. Explicit non-Git targets are registry-only and receive
+  no implicit target tree.
+- An internal caller-ID-only workpad primitive that atomically publishes an
+  empty, unborn, local-only Git repository under the configured mount. It sets
+  repository-local identity and ownership markers, configures no remote, and
+  creates no Gig proposal, semantic file, commit, or active selection.
+- One offline proposal lifecycle that allocates a Gig, provisions its private
+  workpad, records semantic local-Git handoffs, and may approve an immutable
+  version without starting a Run.
+- Installed `gigs`, `proposals`, `status`, `show`, `history`, `plan`, `workpad
+  path`, and `open` commands over explicit or active registered workpads.
+  `state.sqlite` is rebuilt from committed journal authority when needed.
+- A reusable black-box scenario harness for isolated homes, target and workpad
+  manifests, Git state, subprocess recording, and fail-closed effect checks.
+- Exact-byte golden vectors that the production implementation must preserve.
+- Executable evidence for schema instances, graph semantics, canonicalization,
+  concurrent journal sequencing, and bounded Phase 0 feasibility questions.
+- A source suite covering canonical bytes, CLI/process isolation, setup,
+  binding, workpads, journal recovery, proposal lifecycle, contract validators,
+  model-port boundaries, and rebuildable index semantics.
+- A wheel-level verifier that proves the exact eight schema resources and their
+  SHA-256 identities survived packaging.
+
+The [V14 implementation plan](docs/architecture/v14-implementation-plan.md)
+defines the intended product. The [command sheet](docs/reference/command-sheet.md)
+contains both the implemented surface and planned design; this README and
+installed help state what works today. The
+[cheat sheet](docs/reference/cheat-sheet.md) is the copy-paste guide for the
+current installation and local workflow.
+
+## Install the published release
+
+GigAI's first production pre-alpha release is `0.1.2`. Once it is published, install
+the exact reviewed release on a clean macOS or Linux machine without cloning
+this repository:
+
+~~~bash
+uv tool install "gigai==0.1.2"
+gigai --version
+gigai --help
+~~~
+
+Choose every update deliberately by replacing the pinned version after reading
+its release notes; GigAI does not self-update:
+
+~~~bash
+uv tool install --reinstall "gigai==0.1.2"
+~~~
+
+## Verify the source evidence
+
+Python 3.11 or newer is required. Compatibility is continuously tested rather
+than capped without evidence; see
+[ADR 0001](docs/adr/0001-python-version-range.md).
+
+~~~bash
+uv sync --extra test
+uv run pytest
+~~~
+
+All configured source tests must pass.
+
+## Configure, diagnose, bind, and inspect existing workpads
+
+GigAI v1 currently supports macOS and Linux. Interactive setup reviews the
+selected machine-state directory, authoritative workpad mount, and structured
+editor command before applying anything:
+
+~~~bash
+gigai setup
+gigai doctor
+gigai doctor --json
+~~~
+
+For automation, `gigai setup --non-interactive` accepts explicit `--home`,
+`--workpad-root`, `--editor`, and repeated `--editor-arg` values. Credential
+configuration accepts references such as
+`--credential-ref provider=environment:PROVIDER_API_TOKEN`; it never accepts
+or copies the referenced value. Run `gigai setup --help` for the complete
+current contract.
+
+After setup, bind the current Git repository without changing tracked content:
+
+~~~bash
+cd /path/to/repository
+gigai init
+gigai init --json
+~~~
+
+Git init writes only the ignored `.gigai/project.toml` binding and the
+user-local registry, while adding one `/.gigai/` entry to
+`.git/info/exclude`. Existing dirty status and file bytes are preserved. An
+explicit non-Git directory is supported without creating `.gigai` inside it:
+
+~~~bash
+gigai init --target /path/to/non-git-directory
+~~~
+
+`init` does not create a Gig, workpad, journal, or remote. The offline
+`create` lifecycle owns Gig-ID allocation and invokes G05's private substrate;
+there is deliberately no standalone public provision or activate command.
+
+Create and review a non-executable proposal locally:
+
+~~~bash
+gigai create research-gigai
+gigai feedback <proposal-id> --text "clarify the verification"
+gigai revise <proposal-id> --change "clarify the verification"
+gigai approve <proposal-id>
+~~~
+
+Creation, feedback, revision, approval, and rejection write only the private
+workpad journal. Approval starts no Run and no target mutation.
+
+The current offline read/open surface is:
+
+~~~bash
+gigai workpad path <gig-id>
+gigai open <gig-id>
+gigai open <gig-id> --with-target
+gigai open --target
+gigai gigs --json
+gigai proposals <gig-id> --json
+gigai status <gig-id> --json
+gigai history <gig-id> --json
+gigai plan <gig-id> --json
+~~~
+
+Without an explicit Gig ID, `workpad path` and `open` resolve the active private
+workpad. They return typed `no_active_gig` only when the bound target has no
+active Gig.
+
+## Canonical identity API
+
+The shipped [gigai.canonical](src/gigai/canonical.py) module is the only product
+implementation of canonical rendering and SHA-256 identity. Its API keeps
+owned and imported bytes visibly separate:
+
+~~~python
+from gigai.canonical import (
+    canonical_json_bytes,
+    canonical_json_digest,
+    canonicalize_owned_text,
+    digest_imported_bytes,
+)
+~~~
+
+`canonicalize_owned_text()` applies GigAI's UTF-8/LF/final-newline contract.
+`digest_imported_bytes()` accepts bytes only and hashes them exactly as read;
+it never performs implicit decoding, encoding, or normalization. The same
+module owns canonical front matter, prefixed UUIDv4 IDs, and explicit active or
+requested Gig-version resolution.
+
+## Verify the built artifact
+
+The wheel verifier is deliberately separate from the source test suite. Tests
+are not shipped in the wheel.
+
+~~~bash
+rm -rf dist
+uv build
+uv venv --python 3.11 .wheel-venv
+version="$(python -c 'import tomllib; print(tomllib.load(open("pyproject.toml", "rb"))["project"]["version"])')"
+set -- "dist/gigai-${version}-"*.whl
+if [ "$#" -ne 1 ] || [ ! -f "$1" ]; then
+  echo "expected exactly one built GigAI wheel for version ${version}" >&2
+  exit 1
+fi
+uv pip install --python .wheel-venv/bin/python "$1"
+.wheel-venv/bin/python tools/verify_installed_schemas.py
+.wheel-venv/bin/python tools/verify_installed_canonical.py
+.wheel-venv/bin/python tools/verify_installed_cli.py
+.wheel-venv/bin/python tools/verify_installed_g03.py
+.wheel-venv/bin/python tools/verify_installed_g04.py
+.wheel-venv/bin/python tools/verify_installed_g05.py
+.wheel-venv/bin/python tools/verify_installed_g06.py
+.wheel-venv/bin/python tools/verify_installed_g07.py
+.wheel-venv/bin/python tools/verify_installed_g08.py
+.wheel-venv/bin/python tools/verify_installed_g09.py
+.wheel-venv/bin/python tools/verify_installed_g11.py
+~~~
+
+Expected result:
+
+~~~text
+verified 8 installed GigAI schemas
+verified installed GigAI canonical identity API
+verified installed GigAI CLI: help, version, setup, doctor, init, create, feedback, revise, approve, reject, gigs, proposals, status, show, history, plan, workpad path, check, and open only
+verified installed GigAI G03 setup, idempotency, pack, and offline doctor
+verified installed GigAI G04 Git and non-Git target binding
+verified installed GigAI G05 private unborn workpad and read/open surface
+verified installed GigAI G06 journal locking and recovery
+verified installed GigAI G07 contract validators
+verified installed GigAI G08 offline proposal lifecycle
+verified installed GigAI G09 rebuildable index and read commands
+verified installed GigAI G11 model invocation foundation
+~~~
+
+The lockfile is committed. CI and release verification use uv with
+`--locked`. A standards-based fallback remains available:
+
+~~~bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install -e ".[test]"
+python -m pytest
+~~~
+
+## Repository map
+
+| Path | Purpose | Shipped |
+|---|---|---|
+| src/gigai/cli.py | Installed setup, diagnostics, binding, offline lifecycle, read, and open surface | yes |
+| src/gigai/canonical.py | Sole canonical byte, digest, ID, and version implementation | yes |
+| src/gigai/config.py | Strict versioned typed machine configuration | yes |
+| src/gigai/setup.py | Idempotent setup orchestration and mount preflight | yes |
+| src/gigai/diagnostics.py | Structured offline installation and mount checks | yes |
+| src/gigai/project_binding.py | Strict path-free Git target binding contract | yes |
+| src/gigai/registry.py | Strict v2 private project/workpad registry and v1 migration | yes |
+| src/gigai/target_binding.py | Git/non-Git identity, reconciliation, and init effects | yes |
+| src/gigai/workpad.py | Caller-ID-only private Git substrate, resolution, active authority, and editor boundary | yes |
+| src/gigai/adapters/ | Deterministic fixture-backed offline adapter | yes |
+| src/gigai/data/ | Immutable built-in standard-pack resources | yes |
+| src/gigai/schemas/ | Single canonical source for versioned serialized contracts | yes |
+| tests/scenarios/ | Installed-process isolation and observation harness | no |
+| research/contract_spike/ | Executable contract and concurrency proof | no |
+| research/phase0_spike/ | Bounded feasibility evidence | no |
+| research/experiments/ | Supporting experiments and sanitized fixtures | no |
+| docs/architecture/ | Approved product and authority design | no |
+| docs/reference/ | Planned operator-facing command contract | no |
+| docs/research/ | Research records and maturity boundaries | no |
+| tools/ | Maintained repository and artifact verification | no |
+
+The [schema README](src/gigai/schemas/README.md) documents canonical bytes,
+identifiers, version selection, journal ordering, and validation beyond JSON
+Schema.
+
+## Non-negotiable boundaries
+
+- Proposals do not execute and cannot approve themselves.
+- Approval creates an immutable version and starts no run.
+- A run invocation grants authority for exactly one run.
+- Workpads remain local and are never published by GigAI.
+- SQLite is rebuildable; committed workpad records are authoritative.
+- GigAI has no hosted history, background sync, or telemetry service.
+- Provider and tool calls are explicit user-authorized exposure.
+
+## Roadmap
+
+The next product work follows the canonical [Phase 1 G00-G11 development goal
+graph](docs/development/goals/phase-1/README.md), derived from the V14 plan.
+Product modules enter src/gigai/ only through an explicit implementation goal
+and acceptance tests. The installed entry point exposes only behavior that
+exists; planned command names are not shipped as placeholders for appearances.
+
+## Contributing and security
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before changing contracts or research
+evidence. Report vulnerabilities according to [SECURITY.md](SECURITY.md).
+Participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
+
+Licensed under the [Apache License 2.0](LICENSE).