ace-core 0.1.0__tar.gz

ace_core-0.1.0/.env.example

@@ -0,0 +1,55 @@
+# SurrealDB
+SURREAL_URL=ws://localhost:8001
+SURREAL_NS=ace
+SURREAL_DB=ace
+SURREAL_USER=root
+SURREAL_PASS=root
+
+# JWT (generate with: openssl rand -hex 32)
+JWT_SECRET=replace-me-with-32-byte-hex-string
+
+# API authentication — the credential `POST /auth/token` exchanges for a
+# bearer JWT. Required before `ace run` (or any authenticated API call)
+# works; see docs/build-your-first-extension.md, step 3, for the one-time
+# token bootstrap. This placeholder is fine for local dev — replace it
+# for anything reachable beyond localhost.
+API_KEY=local-dev-only-not-a-secret
+# Optional: place CLI/MCP token state outside ~/.ace (useful for CI or disposable rehearsals).
+# ACE_CONFIG_DIR=/absolute/path/to/disposable/config
+
+# LLM — replace this placeholder with one usable provider before running `ace doctor`.
+# For Anthropic API use, paste your real key here. BYOK alternatives are in docs/providers.md.
+LLM_API_KEY=sk-test-placeholder
+LLM_MODEL=claude-sonnet-5
+LLM_BUDGET_MODEL=claude-haiku-4-5-20251001
+LLM_REASONING_MODEL=claude-opus-4-8
+LLM_FRONTIER_MODEL=claude-fable-5
+# Effort is independent of model choice. `default` omits the override.
+LLM_BUDGET_EFFORT=default
+LLM_EFFORT=default
+LLM_REASONING_EFFORT=high
+LLM_FRONTIER_EFFORT=xhigh
+
+# ChatGPT subscription route (no OpenAI Platform API key): first run `codex login`,
+# then uncomment these lines. Use `claude` or `auto` to retain the Claude route.
+# SUBSCRIPTION_PROVIDER=codex
+# CODEX_CLI_MODEL=gpt-5.6-terra
+# CODEX_CLI_EFFORT=default
+# CODEX_CLI_EFFORT_MAP='{"claude-opus-4-8":"high","claude-fable-5":"xhigh"}'
+# REQUIRE_SUBSCRIPTION=1
+
+# GitHub (for ace_research_repo, gh CLI fallback)
+GITHUB_TOKEN=your_github_token_here
+
+# Firecrawl (self-hosted — full web scraping stack)
+FIRECRAWL_URL=http://localhost:3002
+FIRECRAWL_API_KEY=ace-local-key
+
+# Extra CORS origins (comma-separated) for dev access from other devices
+# (LAN/VPN). Appended to the environment's built-in localhost defaults.
+# CORS_EXTRA_ORIGINS=http://<lan-ip>:5173,http://<vpn-ip>:5173
+
+# Discord (proactive PM notifications)
+ACE_DISCORD_BOT_TOKEN=your-bot-token
+ACE_DISCORD_USER_ID=your-discord-user-id
+ACE_DISCORD_CHANNEL_ID=your-channel-id

ace_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+Notable user- and contributor-visible changes are recorded here.
+
+## 0.1.0
+
+- Initial developer preview of the `ace-core` Python distribution, preserving the `ace` import
+  package, `ace` CLI command, and version `0.1.0`.
+- The supported public interaction boundary is the thin 11-tool MCP package and CLI.
+- Atrium remains a separate experimental visual-product/research track and releases as public
+  repository beta source while staying outside the Python wheel/sdist, golden path,
+  supported-runtime claims, and supported release contract.
+- The frozen `ace-preview-surface-v1` M2 scenario proved one durable preference survived restart
+  and materially affected a later decision. Its matched-model evidence is n=1 and does not support
+  a general superiority claim.
+- Python packaging includes the kernel, CLI, thin MCP client, schema migrations, reference
+  extension, evaluation material, public documentation, license, and notice while excluding
+  Atrium beta source and local state.
+- `ace doctor` validates a protected authenticated request and reports the effective provider-neutral
+  model policy; `ace model-policy` exposes fast/capable/frontier mapping and degraded state.
+- Supported Python is 3.12; the SurrealDB Python client is constrained to the compatible 1.x line.
+- The heavyweight CodeSage/PyTorch embedding backend is now an explicit `codesage` extra; the
+  default ONNX-backed install no longer pulls GPU/CUDA packages into the release container.
+
+Release entries separate supported, experimental, fixed, security, migration, and known-
+limitation notes.

ace_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,156 @@
+# Contributing to ACE
+
+ACE is an open-source reasoning kernel — the engine that powers partner-team reasoning across any
+domain. The 0.1.0 contribution path covers the kernel, CLI/thin MCP contract, evaluation, docs, and
+extension ecosystem. Atrium is a separately gated experimental visual-product/research track.
+
+**Before you start, please read:**
+- [`ROADMAP.md`](ROADMAP.md) — the public priorities and longer-term direction
+- [`docs/capability-maturity.md`](docs/capability-maturity.md) — which surfaces are supported, experimental, conditional, dormant, or planned
+- [`docs/architecture.md`](docs/architecture.md) — how the system works today
+- [`docs/build-your-first-extension.md`](docs/build-your-first-extension.md) — the contributor entry point if you're building an extension
+
+---
+
+## Setup
+
+Prerequisites are Git, Python 3.12, `uv`, and Docker Engine with Compose v2. SurrealDB listens on
+**8001**, not its upstream default port. Atrium's experimental visual-product/research track has a
+separate Node.js toolchain and is not part of preview setup. The ACE kernel is Apache-2.0; the
+separately run SurrealDB server is
+source-available under BSL 1.1 rather than OSI open source.
+
+```bash
+# Backend (Python 3.12)
+git clone <your-clone-url>              # e.g. your fork of this repository
+cd ace                                  # the cloned directory
+cp .env.example .env                    # set JWT_SECRET, API_KEY, and one real provider
+docker compose -f infra/docker-compose.yml up -d surrealdb
+uv sync                                 # installs Python deps
+uv run python scripts/schema_apply.py
+uv run uvicorn core.engine.api.main:app --host 127.0.0.1 --port 3000
+
+# In another terminal
+uv run ace login --api-key '<API_KEY from .env>'
+uv run ace doctor
+uv run ace model-policy
+uv run python scripts/verify_golden_path.py
+
+```
+
+See the [README](README.md) quickstart for the authoritative end-to-end setup.
+
+MCP and CLI are the developer-preview interaction paths. Atrium—the experimental
+visual-product/research track—is present as a repository beta, not a supported Python artifact or
+prerequisite for contributing to the engine.
+
+---
+
+## How to contribute
+
+### 1. Find or open an issue
+
+- Bugs: include reproduction steps, expected vs actual behavior, and the relevant subsystem (classifier / composer / deep committee / canvas / sentinel / foresight).
+- Features: open a discussion first if the change touches an architectural contract from [`docs/architecture.md`](docs/architecture.md).
+
+### 2. Pick the right surface
+
+| You want to... | Touch this |
+|---|---|
+| Add a domain-specific recipe, persona, framework, or tool | An extension — see [`docs/build-your-first-extension.md`](docs/build-your-first-extension.md). Don't add it to the kernel. |
+| Fix a kernel bug or improve a layer's behavior | `core/engine/{orchestrator,orchestration,cognition,capture,sentinel,foresight}/` |
+| Add or evaluate an orchestration pattern | `core/engine/orchestration/` and `tests/orchestration/` |
+| Add a MAKE or SHIP capability | `core/engine/arms/` with focused tests under `tests/` |
+| Propose an Atrium HCI research change | Begin with the isolated research packet; do not expand the preview artifact |
+| Improve evaluation and conformance | `tests/`, especially orchestration, intelligence, extension, and naked-kernel boundaries |
+
+### 3. Run the tests
+
+```bash
+uv run pytest path/to/test_file.py -q       # focused check while iterating
+make test-fast                          # pytest excluding e2e
+ACE_DISABLE_EXTENSIONS=1 uv run pytest -m "not e2e and not requires_extensions" -q --tb=short
+uv run ruff check <changed-python-files>
+```
+
+For extension changes, also run the extension's own test suite if it ships one (e.g. `uv run pytest extensions/<your-extension>/tests/ -m "not e2e"`); the reference extension (`extensions/reference/`) is covered by `tests/extensions/`.
+
+Markers distinguish `e2e` and `requires_extensions` work from the default deterministic suite.
+Do not make provider-quality claims from credential-free fixtures; follow
+[`evaluations/README.md`](evaluations/README.md) for matched-model evidence and paid-live guards.
+
+### 4. Conventions
+
+**Commits:**
+- Conventional commits format: `feat(area): summary` / `fix(area):` / `docs(area):` / `chore(area):` / `refactor(area):` / `test(area):`
+- Body explains the *why*, not the *what* (the diff shows what)
+- No AI co-author attribution — write what you wrote
+- Never use `--no-verify` to skip hooks; fix the underlying issue
+
+**Code:**
+- Python: snake_case everything (modules, functions, files). Use `get_llm()` rather than raw provider imports.
+- SurrealDB access uses `from core.engine.core.db import pool`, `async with pool.connection() as db`,
+  `parse_rows(result)` for results, and `serialize_record(obj)` before JSON output. Add migrations
+  under `core/schema/`, apply them with `uv run python scripts/schema_apply.py`, and test
+  against namespace `ace_test`.
+- TypeScript: no inline `color:` / `font-size:` / `padding:` — compose from `core/ui/canvas/src/design/components/`. New patterns extend the design system *first*, get used *second*.
+- Tests live next to the code they cover. Extension tests in `<extension>/tests/`, kernel tests in `tests/`.
+
+**Pull requests:**
+- One concept per PR. Split big changes into atomic commits with tests green between them.
+- Reference the issue (`Fixes #N`) if applicable
+- Describe the *blast radius* — which subsystems, which tests, what could break
+- Wait for CI green before requesting review
+- Include focused and required conformance commands with exact results, documentation changes for
+  public behavior, and evidence for maturity or performance claims. Link roadmap work to a public
+  issue or Project item when one exists.
+- Never include credentials, private graph exports, proprietary fixtures, or private-extension code.
+
+The thin 11-tool MCP package and CLI are the preview contracts. The broad HTTP API, internal MCP
+host, Atrium UI seams, and experimental extension hooks may change. Propose stable-contract changes
+before implementation using [`docs/governance.md`](docs/governance.md).
+
+### 5. Architectural contracts (don't break these)
+
+These are described in [`docs/architecture.md`](docs/architecture.md). They are stable; changes to them require an explicit decision:
+
+- **Provider Agnosticism** — no specific LLM provider in engine imports. Always `get_llm()`.
+- **Surface Agnosticism** — engine emits events; surfaces subscribe. No UI imports in engine modules.
+- **Modularity** — capabilities are recipe + instrument combinations addressable by slug.
+- **Decision Lineage** — every meaningful choice gets a `graph_decision` row.
+- **Forward Momentum** — every synthesis emits a forward-looking next move.
+- **Nested Partnership** — `Human ↔ ACE ↔ LLM`. The LLM is computation, not loop controller.
+- **Adaptive Framework Orchestration** — recipes select frameworks dynamically.
+- **Mandatory Design System Use** — every UI component composes from `core/ui/canvas/src/design/components/`.
+
+### 6. Extensions: the recommended contribution path
+
+Don't copy `extensions/reference/` by hand — scaffold it:
+
+```bash
+python -m scripts.scaffold_extension <your_domain>
+```
+
+This copies the shipped reference extension and renames every identifier for
+you (class, discipline, recipe, tool), so your starting point is a fully
+wired, fully working extension, not a stub. From there:
+
+1. Wire your recipes, instruments, personas, frameworks through the `Registry` facade.
+2. Register via `ace.extensions` Python entry point (the scaffold wires this too).
+3. Your extension package carries its own `tests/` — run them with `pytest` from your package. (Extensions living in-tree under `extensions/` are still picked up by the kernel's test discovery.)
+
+The tutorial is canonical: [`docs/build-your-first-extension.md`](docs/build-your-first-extension.md) walks the full flow, file by file. Exact `Registry` contract: [`docs/extension-api.md`](docs/extension-api.md).
+
+---
+
+## Discussion
+
+- **GitHub Issues** — bugs, feature requests
+- **GitHub Discussions** — architecture questions, design discussions, "is this an extension or a kernel change?"
+- **Security** — see [`SECURITY.md`](SECURITY.md). Do not file security issues in public GitHub Issues.
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the Apache License 2.0 (see [`LICENSE`](LICENSE)). You retain copyright to your contributions; you grant the project a perpetual license to use them under Apache-2.0.

ace_core-0.1.0/Dockerfile

@@ -0,0 +1,31 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+RUN pip install --no-cache-dir uv
+
+# Install the same complete source surface used to build the wheel. The old
+# order installed an editable project before its packages existed and omitted
+# the thin MCP client, README, and license metadata from the image entirely.
+COPY pyproject.toml uv.lock build_backend.py README.md ROADMAP.md CONTRIBUTING.md SECURITY.md CHANGELOG.md LICENSE NOTICE ./
+COPY core/ core/
+COPY extensions/ extensions/
+COPY ace_mcp_client/ ace_mcp_client/
+COPY scripts/ scripts/
+COPY evaluations/ evaluations/
+COPY docs/ docs/
+RUN uv pip install --system --no-cache .
+
+# Run as non-root for security — prevents container escapes from writing host files
+RUN adduser --disabled-password --gecos "" aceuser && chown -R aceuser /app
+USER aceuser
+
+EXPOSE 3000
+
+# Liveness probe: always 200 if the event loop is alive.
+# Use /health/live (not /health/ready) so Docker doesn't restart healthy
+# instances while the DB is temporarily unavailable at startup.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=15s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:3000/health/live')" || exit 1
+
+CMD ["uvicorn", "core.engine.api.main:app", "--host", "0.0.0.0", "--port", "3000"]

ace_core-0.1.0/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 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 Support. 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 support.
+
+   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 2026 Edwin Amirian
+
+   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.

ace_core-0.1.0/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md ROADMAP.md CONTRIBUTING.md SECURITY.md CHANGELOG.md LICENSE NOTICE
+include Dockerfile Makefile .env.example uv.lock
+include build_backend.py
+recursive-include ace_mcp_client *.py
+recursive-include core *.py *.surql
+recursive-include extensions *.py *.md
+recursive-include scripts *.py
+recursive-include evaluations *.json *.md
+recursive-include docs *.md
+prune .github
+prune tests
+prune core/ui
+global-exclude *.py[cod] .DS_Store
+global-exclude __pycache__