marifai-harness 0.3.0__tar.gz

marifai_harness-0.3.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+# .github/workflows/ci.yml
+name: Python SDK and SQLite acceptance
+on: [push, pull_request, workflow_dispatch]
+permissions:
+  contents: read
+jobs:
+  local:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, ubuntu-latest, macos-latest]
+        python: ['3.12', '3.13', '3.14']
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ruff check src tests scripts examples
+      - run: python -m pytest -q --junitxml=dist/evidence/tests.xml
+      - run: python -m build
+      - shell: pwsh
+        run: |
+          # Installed package acceptance in an independent environment.
+          python -m venv .package-consumer
+          $python = if ($IsWindows) { '.package-consumer/Scripts/python.exe' } else { '.package-consumer/bin/python' }
+          & $python -m pip install (Get-Item dist/*.whl).FullName
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          & $python scripts/package_smoke.py .cache/consumer | Tee-Object -FilePath dist/evidence/consumer.json
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          & $python -m marifai.cli --help
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+          & $python tests/test_cli_recovery.py | Tee-Object -FilePath dist/evidence/cli-recovery.json
+          if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }
+      - uses: actions/upload-artifact@v4
+        with:
+          name: package-${{ matrix.os }}-${{ matrix.python }}
+          path: dist/*

marifai_harness-0.3.0/.github/workflows/publish.yml

@@ -0,0 +1,72 @@
+# .github/workflows/publish.yml
+name: Approved PyPI publication
+on:
+  workflow_dispatch:
+    inputs:
+      publish:
+        description: Publish after ownership, license and release evidence review
+        type: boolean
+        default: false
+      approval_json:
+        description: Maintainer approval JSON for this version (required only when publishing)
+        type: string
+        default: ''
+      evidence_json:
+        description: Exact artifact evidence with seven-provider acceptance or an explicit owner waiver
+        type: string
+        default: ''
+      validated_build_run:
+        description: Successful build-only run containing the exact tested release-distributions artifact
+        type: string
+        default: ''
+permissions:
+  contents: read
+jobs:
+  build:
+    if: ${{ !inputs.publish }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - run: python -m pip install build twine
+      - run: python -m build
+      - run: python -m twine check dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-distributions
+          path: dist/*
+  publish:
+    if: inputs.publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      actions: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+      - name: Require an existing successful build of this commit
+        env:
+          GH_TOKEN: ${{ github.token }}
+          VALIDATED_BUILD_RUN: ${{ inputs.validated_build_run }}
+          RELEASE_COMMIT: ${{ github.sha }}
+        run: |
+          # .github/workflows/publish.yml
+          python scripts/publication_gate.py --validate-build-run "$VALIDATED_BUILD_RUN" --expected-commit "$RELEASE_COMMIT"
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-distributions
+          path: dist/
+          run-id: ${{ inputs.validated_build_run }}
+          github-token: ${{ github.token }}
+      - name: Require release-owner metadata and verified artifacts
+        env:
+          RELEASE_APPROVAL_JSON: ${{ inputs.approval_json }}
+          RELEASE_EVIDENCE_JSON: ${{ inputs.evidence_json }}
+        run: python scripts/publication_gate.py --approval-json "$RELEASE_APPROVAL_JSON" --evidence-json "$RELEASE_EVIDENCE_JSON"
+      - uses: pypa/gh-action-pypi-publish@release/v1

marifai_harness-0.3.0/.gitignore

@@ -0,0 +1,35 @@
+# .gitignore
+.venv/
+.cache/
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.marifai/
+dist/
+*.egg-info/
+.env
+.env.*
+!.env.example
+/marifai.toml
+/release-approval.json
+*.sqlite3
+*.sqlite3-wal
+*.sqlite3-shm
+
+# Retained locally from the earlier distributed scope; excluded from this SDK repository.
+/src/marifai/cloud/
+/compose.integration.yml
+/.dockerignore
+/docs/integration.md
+/docs/openapi.json
+/scripts/integration_*
+/scripts/export_openapi.py
+/scripts/release_evidence.py
+/examples/control_plane.py
+/examples/remote_worker.py
+/tests/test_cloud*
+/tests/test_distributed*
+/tests/test_postgres*
+/tests/integration/
+

marifai_harness-0.3.0/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+## 0.3.0 — PyPI-only scope update
+
+- Declare MIT licensing with Sultani Investments author/maintainer metadata and include the license
+  in both release distributions.
+- Add installed-wheel acceptance for the seven explicitly configured services in
+  `examples/acceptance/matrix.json`, retaining the legacy two-provider command.
+- Persist campaign reservations across interruptions and retries, with a $5 total inference cap,
+  $4 first-attempt allowance, $1 retry allowance and retained uncertain charges.
+- Bind provider evidence to the artifact, configuration, fixture and evaluator; require all seven
+  services and exact artifact/license checks before the guarded publication workflow can upload.
+- Add the version-2 coding fixture's exact output and first-line path-comment checks, preserving
+  frozen verification and restricted candidate write scope.
+- Freeze coding acceptance checkers from their fixture manifest and restrict candidate writes
+  to declared implementation paths, so editing a workspace checker cannot manufacture a pass.
+- Make provider acceptance fail closed on unverified work, stale reports, failed child processes
+  and missing required evidence; bind reports to each invocation and exact fixture.
+- Complete the explicit maintainer-approval input for release CI, preserve publish-job checkout
+  permissions, and reject malformed, stale or incomplete publication approvals.
+- Wire SDK/training observability to a separate append-only SQLite trace store or injected sink,
+  with redaction, cursor replay, duplicate suppression and delivery-failure isolation.
+- New runtime databases omit legacy tenancy/remote-job tables; existing tables are preserved.
+- Native Anthropic/Gemini reasoning controls and opaque continuation state, preserved through
+  approval/restart with deployment-bound retries and excluded from traces and training datasets.
+- Installed CLI kill/resume acceptance on Windows and Linux preserves confirmed tool work and uncertain charges.
+- Meter configured remote/paid embeddings with durable application caps, funded run-tool envelopes,
+  pricing provenance, privacy/provider-scope enforcement, ambiguous-charge retention and explicit reconciliation.
+
+- First-party SQLite documents, stable chunks, FTS5/cosine retrieval, source references and policy-gated memory tools.
+- Configured local embeddings, memory context assembly, CLI ingest/search and a runnable RAG example.
+- Native Anthropic/Gemini protocols, normalized invoke/stream, optional provider extras and configurable auth headers.
+- Exact test-command allowlists, bounded HTTP reads, artifact tools and typed policy limits.
+- YAML configuration and a local credential vault with optional encryption at rest.
+- Funded Harness assembly, configurable Archon roles, an effort-based review path and explicit pause/resume.
+- CLI included in the base package; cloud adapters excluded from distributions and cloud service jobs removed from CI.
+- Historical implementation entries below describe earlier scope and do not expand the current PyPI product.
+
+## 0.3.0 — embeddable SDK
+
+- General task graphs and registered agents run without Git; coding remains an explicit strategy.
+- Persistent catalog refresh, metadata provenance/freshness, pinned proxy deployments and passive observations.
+- Prepared plans, complete-envelope funding, one affordable alternative, exact shortfalls, refunds and recovery.
+- Optional authorized dataset exports, grouped splits, logistic shadow routing and evidence-bound activation.
+- Optional native LoRA and Hugging Face Jobs training with durable intents, cancellation and candidate artifacts.
+- Base installation excludes CLI/training dependencies. CLI uses the same catalog and planning APIs.
+- Additive SQLite/PostgreSQL record migration; older persisted coding runs retain their strategy.
+- Confirmed model responses survive interruption before checkpoint handoff without duplicate calls.
+- Resume rechecks funding, retains uncertain charges and completed work, and resumes missing verification.
+- `Run.resume` and `Marifai.resume` accept optional narrower policies and lower limits under the
+  executor lease. Immediate cancellation before driver startup is durable and releases the lease.
+- Context/output limits now default to unknown. Routing requires explicit or discovered bounds.
+  Existing configurations that relied on implicit limits must declare the actual deployment limits.
+- Unmeasured health/reliability/latency remain unknown; failed observations survive restart and
+  explicit configuration takes precedence over passive metadata.
+- Coordinator phase names are reserved graph IDs; duplicate criterion/phase identities are rejected.
+- Routing evaluation requires equal task requirements, authority and limits in held-out pairs;
+  dataset readers enforce disjoint groups and complete tool-call/result sequences.
+- Training backend contract version 2 adds identity-checked reconciliation. Ambiguous cancellation
+  remains blocked; completed hosted artifacts reference a private repository's immutable revision.
+- Release artifacts and CI publication workflow are prepared; publication requires ownership, licensing and approval.
+
+## 0.2.0 — initial implementation
+
+- Added async Python SDK and CLI, OpenAI-compatible/Ollama streaming adapters, deterministic routing,
+  four autonomy modes, custom/native tools, atomic resource reservations, durable SQLite runs,
+  approval/recovery/cancellation, and artifact lineage.
+- Added bounded Archon coding graphs, separate Git worktrees, deterministic verification,
+  independent review, correction, and patch delivery preserving the source checkout.
+- Added optional PostgreSQL runtime, authenticated REST/SSE control plane, worker fencing,
+  tenant budgets, worker affinity and S3-compatible artifact uploads.
+- Added credential-free first-run configuration with `init` and `doctor`, plus disposable
+  PostgreSQL/S3 services and a remote-worker acceptance test over actual HTTP connections.
+- Added deterministic acceptance tests, explicit live integration gates, cross-platform CI,
+  examples and package build configuration. This version number does not imply production
+  acceptance of integrations whose live gates have not run.
+

marifai_harness-0.3.0/LICENSE

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

marifai_harness-0.3.0/PKG-INFO

@@ -0,0 +1,194 @@
+Metadata-Version: 2.5
+Name: marifai-harness
+Version: 0.3.0
+Summary: Embeddable agent execution, orchestration, subagents and funded resource governance
+Project-URL: Repository, https://github.com/sultani-investments/marifai-harness-sdk
+Author: Sultani Investments
+Maintainer: Sultani Investments
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: httpx<1,>=0.28
+Requires-Dist: jsonschema<5,>=4.23
+Requires-Dist: pydantic<3,>=2.10
+Requires-Dist: typer<1,>=0.15
+Provides-Extra: anthropic
+Provides-Extra: cli
+Requires-Dist: typer<1,>=0.15; extra == 'cli'
+Provides-Extra: credentials
+Requires-Dist: cryptography>=44; extra == 'credentials'
+Requires-Dist: keyring>=25; extra == 'credentials'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: cryptography>=44; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.25; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml<7,>=6; extra == 'dev'
+Requires-Dist: ruff>=0.9; extra == 'dev'
+Provides-Extra: gemini
+Provides-Extra: learning
+Requires-Dist: scikit-learn>=1.6; extra == 'learning'
+Provides-Extra: ollama
+Provides-Extra: openai
+Provides-Extra: openrouter
+Provides-Extra: togetherai
+Provides-Extra: training-hosted
+Requires-Dist: huggingface-hub<2,>=1.33; extra == 'training-hosted'
+Provides-Extra: training-local
+Requires-Dist: datasets<6,>=5; extra == 'training-local'
+Requires-Dist: peft<1,>=0.21; extra == 'training-local'
+Requires-Dist: torch<3,>=2.14; extra == 'training-local'
+Requires-Dist: transformers<6,>=5.17; extra == 'training-local'
+Requires-Dist: trl<2,>=1.14; extra == 'training-local'
+Provides-Extra: xai
+Provides-Extra: yaml
+Requires-Dist: pyyaml<7,>=6; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Marifai Harness
+
+A Python SDK for embedding durable agents, orchestration and bounded subagents in other applications.
+Distribution: `marifai-harness`. Public import: `marifai`. Python 3.12 or newer.
+
+The consuming application owns its interface, business logic, hosting and deployment. The harness
+and Archon share provider contracts, policy, a durable SQLite runtime, resource accounting, registered tools,
+and first-party SQLite RAG memory. This distribution has no frontend, hosted control plane or organization tenancy.
+General graphs run without Git. The explicit coding strategy adds snapshots, writer worktrees,
+patch integration and deterministic checks. The core needs no server, Docker or cloud account.
+
+Built-in tools provide scoped file I/O, allow-listed HTTP reads, artifacts, and memory. Commands require
+an exact argument-list entry in `Policy.test_commands`; arbitrary shell execution is not available.
+Approved test programs and custom Python tools still run with the application's host privileges.
+
+## Install and configure
+
+The PyPI distribution is `marifai-harness`; 0.3.0 artifacts are prepared locally but have not been
+published. Install the wheel with `python -m pip install dist/marifai_harness-0.3.0-py3-none-any.whl`
+or use `python -m pip install .` from this checkout. After publication, applications can use
+`python -m pip install marifai-harness`. For development use `python -m pip install -e ".[dev]"`.
+
+The CLI is a developer utility included in the base package. Run
+`marifai init` to create `marifai.toml` without credentials or an implicit provider. Run
+`marifai doctor` to inspect configuration readiness. The CLI automatically reads `marifai.toml`
+from its current directory, or an explicit `--config` path. Existing configuration is never overwritten.
+To write a selected deployment directly, `init` accepts `--kind`, `--base-url`, `--model`,
+`--credential-env`, repeated `--capability` flags, prices, and a run USD cap. Secrets remain in the
+referenced environment variable. `doctor --connect` performs model discovery, never inference.
+If the scaffold already exists, edit it or use `init --output another-config.toml` with the selected settings.
+Copy `examples/marifai.toml` to your own configuration and explicitly select your endpoints,
+deployments, capabilities, and prices. Credentials use `env:VARIABLE`, `vault:NAME`, or `keyring:NAME` references.
+No endpoint, model, cloud service, or local inference process is enabled automatically.
+
+Run `marifai --help`, then `marifai models --config your-config.toml` to inspect your catalog.
+`marifai run "Explain this repository" --config your-config.toml` starts a single agent.
+Add `--archon --strategy coding` for the coding coordinator and `--test '["python","-m","pytest"]'` for explicit
+deterministic acceptance. `--usd 1.00` sets a run monetary cap; paid deployments require one.
+
+Autonomy values are `approve_writes`, `scoped`, `broad`, and `autonomous`. The default is `scoped`.
+An autonomy setting never creates missing grants. Configure broader grants through the SDK policy.
+
+Use `marifai inspect RUN_ID`, `marifai approve RUN_ID APPROVAL_ID`, and `marifai resume RUN_ID`
+for paused runs. `marifai cancel RUN_ID` requests cancellation. CLI processes wait for execution;
+interrupting them leaves durable checkpoints for subsequent inspection and recovery.
+
+## Python SDK
+
+See `examples/embedded_graph.py` for custom tools and non-Git subagents, `examples/agent_loop.py`
+for an application-owned loop, and `examples/coding_task.py` for explicit coding execution.
+The supported application surface is `Marifai` plus `Agent`, `Archon`, `Task`, `Tool`, `Policy`, and `Run`.
+Supporting graph/configuration/contract types are documented in `docs/contracts.md`; internal modules
+are not a public compatibility promise. Existing root aliases for graph/plan types remain available
+for migration. Extension protocols have their own version number.
+
+`Run.wait()` returns an explicit completed/partial/blocked/failed/cancelled result. A completed
+unconstrained response is not proof of correctness: `verified` is true only when declared checks
+pass. Required semantic criteria stay unverified until an external acceptance mechanism exists.
+
+```python
+# examples/prepare_usage.py (illustrative caller fragment)
+from marifai import Agent, Marifai, PlanNode, Policy, Task, TaskGraph
+from marifai.foundation.config import Config
+
+async def execute(config_path, workspace):
+    async with Marifai(Config.load(config_path)) as client:
+        task = Task(instructions="Summarize the supplied material")
+        graph = TaskGraph(tasks=[PlanNode(id="summary", instructions=task.instructions,
+                                         agent="summarizer", model_calls=2, tool_calls=0)])
+        run = await client.archon.prepare(task, graph=graph,
+            agents={"summarizer": Agent(name="summarizer", tools=[])},
+            policy=Policy(workspace=workspace))
+        report = run.plan()
+        if report and report.status == "funded":
+            await run.resume()
+            return await run.wait()
+        return report
+```
+
+Prepare persists the task graph and complete resource envelope before dispatching implementation
+agents. Planning inference, if needed, uses the same ledger. Deployment details, capability evidence,
+pricing source/version, review/retry/correction allowances and precise shortfalls remain inspectable
+after restart. An unaffordable preferred plan gets exactly one least-cost eligible alternative.
+Neither checks nor authority are weakened. Time predictions are estimates; deadlines remain enforced.
+
+`await client.refresh_catalog()` refreshes explicitly configured endpoints and persists observations.
+It never enables newly discovered models. Inspect `client.catalog.snapshot`, `.history()` and
+`.observations()`. Discovered capabilities/prices expire after 24 hours by default; configuration
+overrides need price provenance. Generic OpenAI-compatible, Ollama and explicitly selected OpenRouter
+metadata profiles are supported. OpenRouter financial admission requires a pinned upstream.
+
+Native Anthropic and Gemini, OpenAI-compatible profiles and Ollama use the same Harness.
+See [provider configuration](docs/providers.md). The base import starts no process and contacts no
+provider. Applications supply endpoints, models, credentials and limits explicitly.
+
+## Built-in memory
+
+Use `await client.memory.upsert_document(id, text, source=...)` and `await client.memory.search(query)`
+for durable SQLite retrieval. Keyword search needs no embeddings endpoint. A configured
+OpenAI-compatible embedder enables hybrid FTS/vector retrieval, with explicit pricing and caps for
+remote or paid endpoints. Set `Task(memory_query="...")` to
+retrieve through policy and the tool budget before inference. Agent memory writes require an explicit
+grant and the selected approval rules. See [memory usage](docs/memory.md) and [the runnable example](examples/rag_memory.py).
+
+The CLI exposes `marifai memory upsert notes.txt --id notes`, `marifai memory search "query"`, and
+`marifai run "Summarize" --memory-query "query"`. It uses the same SDK and configured SQLite store.
+
+## State, cost, and privacy
+
+Local state defaults to `.marifai/`: SQLite runtime and memory, immutable artifacts, and managed coding
+worktrees. Preserve that directory to resume runs and inspect delivered patches. Runtime checkpoints
+necessarily contain task instructions, conversation, tool arguments/results, and generated code.
+Protect it like the source repository. Event traces omit model content unless `retain_content=true`;
+credentials are redacted from diagnostic events. There is no automatic training-data upload.
+
+Resource reservations share a parent run ledger across agents. Unknown/ambiguous provider charges
+remain reserved. Provider-reported cost is used when available; usage multiplied by configured
+prices remains labeled an estimate. Unpriced remote deployments and unpriced deployments under
+a strict monetary cap cannot be routed. Local unpriced work still consumes call/token/time limits.
+
+Elapsed wall time includes approval waits and downtime. A run that has exhausted its configured
+wall-time cap cannot resume work; create a new run with a deliberately chosen limit.
+
+Git worktree metadata is shared with the source repository. Baseline snapshots use temporary
+indexes and detached commits; the original index, branch and working files are preserved. Only
+explicitly selected untracked files enter the baseline. Completed worktrees remain available for
+review; there is no automatic cleanup or publishing.
+
+## Verification
+
+Run `python -m pytest` and `python -m build`. Tests use deterministic scripted providers and mock
+HTTP streams; live-provider checks are separate, opt-in tests. Windows and Linux-container suites
+have local evidence; the CI matrix defines additional platform checks. See `docs/validation.md` for current evidence
+and limits, and `docs/architecture.md` for runtime boundaries.
+Cloud adapters are excluded from the wheel and source distribution. No cloud services are needed
+to run the package or its local acceptance checks.
+
+## 0.3.0 provider acceptance
+
+The maintainer explicitly waived live-provider acceptance for this release. Package, license,
+installed SDK smoke, and Windows/macOS/Linux checks remain required. Seven-service live acceptance
+has not passed: an earlier wheel passed Anthropic; OpenAI, Ollama, xAI, and Together did not complete
+all acceptance gates, and Gemini/OpenRouter credentials were unavailable. One Together operation
+retains an unresolved usage reservation. These historical results do not establish live acceptance
+of the published wheel or compatibility with every model. See the
+[complete provider acceptance disclosure](https://github.com/sultani-investments/marifai-harness-sdk/blob/main/docs/releases/0.3.0-provider-acceptance.md).
+

marifai_harness-0.3.0/README.md

@@ -0,0 +1,147 @@
+# Marifai Harness
+
+A Python SDK for embedding durable agents, orchestration and bounded subagents in other applications.
+Distribution: `marifai-harness`. Public import: `marifai`. Python 3.12 or newer.
+
+The consuming application owns its interface, business logic, hosting and deployment. The harness
+and Archon share provider contracts, policy, a durable SQLite runtime, resource accounting, registered tools,
+and first-party SQLite RAG memory. This distribution has no frontend, hosted control plane or organization tenancy.
+General graphs run without Git. The explicit coding strategy adds snapshots, writer worktrees,
+patch integration and deterministic checks. The core needs no server, Docker or cloud account.
+
+Built-in tools provide scoped file I/O, allow-listed HTTP reads, artifacts, and memory. Commands require
+an exact argument-list entry in `Policy.test_commands`; arbitrary shell execution is not available.
+Approved test programs and custom Python tools still run with the application's host privileges.
+
+## Install and configure
+
+The PyPI distribution is `marifai-harness`; 0.3.0 artifacts are prepared locally but have not been
+published. Install the wheel with `python -m pip install dist/marifai_harness-0.3.0-py3-none-any.whl`
+or use `python -m pip install .` from this checkout. After publication, applications can use
+`python -m pip install marifai-harness`. For development use `python -m pip install -e ".[dev]"`.
+
+The CLI is a developer utility included in the base package. Run
+`marifai init` to create `marifai.toml` without credentials or an implicit provider. Run
+`marifai doctor` to inspect configuration readiness. The CLI automatically reads `marifai.toml`
+from its current directory, or an explicit `--config` path. Existing configuration is never overwritten.
+To write a selected deployment directly, `init` accepts `--kind`, `--base-url`, `--model`,
+`--credential-env`, repeated `--capability` flags, prices, and a run USD cap. Secrets remain in the
+referenced environment variable. `doctor --connect` performs model discovery, never inference.
+If the scaffold already exists, edit it or use `init --output another-config.toml` with the selected settings.
+Copy `examples/marifai.toml` to your own configuration and explicitly select your endpoints,
+deployments, capabilities, and prices. Credentials use `env:VARIABLE`, `vault:NAME`, or `keyring:NAME` references.
+No endpoint, model, cloud service, or local inference process is enabled automatically.
+
+Run `marifai --help`, then `marifai models --config your-config.toml` to inspect your catalog.
+`marifai run "Explain this repository" --config your-config.toml` starts a single agent.
+Add `--archon --strategy coding` for the coding coordinator and `--test '["python","-m","pytest"]'` for explicit
+deterministic acceptance. `--usd 1.00` sets a run monetary cap; paid deployments require one.
+
+Autonomy values are `approve_writes`, `scoped`, `broad`, and `autonomous`. The default is `scoped`.
+An autonomy setting never creates missing grants. Configure broader grants through the SDK policy.
+
+Use `marifai inspect RUN_ID`, `marifai approve RUN_ID APPROVAL_ID`, and `marifai resume RUN_ID`
+for paused runs. `marifai cancel RUN_ID` requests cancellation. CLI processes wait for execution;
+interrupting them leaves durable checkpoints for subsequent inspection and recovery.
+
+## Python SDK
+
+See `examples/embedded_graph.py` for custom tools and non-Git subagents, `examples/agent_loop.py`
+for an application-owned loop, and `examples/coding_task.py` for explicit coding execution.
+The supported application surface is `Marifai` plus `Agent`, `Archon`, `Task`, `Tool`, `Policy`, and `Run`.
+Supporting graph/configuration/contract types are documented in `docs/contracts.md`; internal modules
+are not a public compatibility promise. Existing root aliases for graph/plan types remain available
+for migration. Extension protocols have their own version number.
+
+`Run.wait()` returns an explicit completed/partial/blocked/failed/cancelled result. A completed
+unconstrained response is not proof of correctness: `verified` is true only when declared checks
+pass. Required semantic criteria stay unverified until an external acceptance mechanism exists.
+
+```python
+# examples/prepare_usage.py (illustrative caller fragment)
+from marifai import Agent, Marifai, PlanNode, Policy, Task, TaskGraph
+from marifai.foundation.config import Config
+
+async def execute(config_path, workspace):
+    async with Marifai(Config.load(config_path)) as client:
+        task = Task(instructions="Summarize the supplied material")
+        graph = TaskGraph(tasks=[PlanNode(id="summary", instructions=task.instructions,
+                                         agent="summarizer", model_calls=2, tool_calls=0)])
+        run = await client.archon.prepare(task, graph=graph,
+            agents={"summarizer": Agent(name="summarizer", tools=[])},
+            policy=Policy(workspace=workspace))
+        report = run.plan()
+        if report and report.status == "funded":
+            await run.resume()
+            return await run.wait()
+        return report
+```
+
+Prepare persists the task graph and complete resource envelope before dispatching implementation
+agents. Planning inference, if needed, uses the same ledger. Deployment details, capability evidence,
+pricing source/version, review/retry/correction allowances and precise shortfalls remain inspectable
+after restart. An unaffordable preferred plan gets exactly one least-cost eligible alternative.
+Neither checks nor authority are weakened. Time predictions are estimates; deadlines remain enforced.
+
+`await client.refresh_catalog()` refreshes explicitly configured endpoints and persists observations.
+It never enables newly discovered models. Inspect `client.catalog.snapshot`, `.history()` and
+`.observations()`. Discovered capabilities/prices expire after 24 hours by default; configuration
+overrides need price provenance. Generic OpenAI-compatible, Ollama and explicitly selected OpenRouter
+metadata profiles are supported. OpenRouter financial admission requires a pinned upstream.
+
+Native Anthropic and Gemini, OpenAI-compatible profiles and Ollama use the same Harness.
+See [provider configuration](docs/providers.md). The base import starts no process and contacts no
+provider. Applications supply endpoints, models, credentials and limits explicitly.
+
+## Built-in memory
+
+Use `await client.memory.upsert_document(id, text, source=...)` and `await client.memory.search(query)`
+for durable SQLite retrieval. Keyword search needs no embeddings endpoint. A configured
+OpenAI-compatible embedder enables hybrid FTS/vector retrieval, with explicit pricing and caps for
+remote or paid endpoints. Set `Task(memory_query="...")` to
+retrieve through policy and the tool budget before inference. Agent memory writes require an explicit
+grant and the selected approval rules. See [memory usage](docs/memory.md) and [the runnable example](examples/rag_memory.py).
+
+The CLI exposes `marifai memory upsert notes.txt --id notes`, `marifai memory search "query"`, and
+`marifai run "Summarize" --memory-query "query"`. It uses the same SDK and configured SQLite store.
+
+## State, cost, and privacy
+
+Local state defaults to `.marifai/`: SQLite runtime and memory, immutable artifacts, and managed coding
+worktrees. Preserve that directory to resume runs and inspect delivered patches. Runtime checkpoints
+necessarily contain task instructions, conversation, tool arguments/results, and generated code.
+Protect it like the source repository. Event traces omit model content unless `retain_content=true`;
+credentials are redacted from diagnostic events. There is no automatic training-data upload.
+
+Resource reservations share a parent run ledger across agents. Unknown/ambiguous provider charges
+remain reserved. Provider-reported cost is used when available; usage multiplied by configured
+prices remains labeled an estimate. Unpriced remote deployments and unpriced deployments under
+a strict monetary cap cannot be routed. Local unpriced work still consumes call/token/time limits.
+
+Elapsed wall time includes approval waits and downtime. A run that has exhausted its configured
+wall-time cap cannot resume work; create a new run with a deliberately chosen limit.
+
+Git worktree metadata is shared with the source repository. Baseline snapshots use temporary
+indexes and detached commits; the original index, branch and working files are preserved. Only
+explicitly selected untracked files enter the baseline. Completed worktrees remain available for
+review; there is no automatic cleanup or publishing.
+
+## Verification
+
+Run `python -m pytest` and `python -m build`. Tests use deterministic scripted providers and mock
+HTTP streams; live-provider checks are separate, opt-in tests. Windows and Linux-container suites
+have local evidence; the CI matrix defines additional platform checks. See `docs/validation.md` for current evidence
+and limits, and `docs/architecture.md` for runtime boundaries.
+Cloud adapters are excluded from the wheel and source distribution. No cloud services are needed
+to run the package or its local acceptance checks.
+
+## 0.3.0 provider acceptance
+
+The maintainer explicitly waived live-provider acceptance for this release. Package, license,
+installed SDK smoke, and Windows/macOS/Linux checks remain required. Seven-service live acceptance
+has not passed: an earlier wheel passed Anthropic; OpenAI, Ollama, xAI, and Together did not complete
+all acceptance gates, and Gemini/OpenRouter credentials were unavailable. One Together operation
+retains an unresolved usage reservation. These historical results do not establish live acceptance
+of the published wheel or compatibility with every model. See the
+[complete provider acceptance disclosure](https://github.com/sultani-investments/marifai-harness-sdk/blob/main/docs/releases/0.3.0-provider-acceptance.md).
+

marifai_harness-0.3.0/docs/architecture.md

@@ -0,0 +1,21 @@
+# Runtime boundaries
+
+Marifai Harness is an embeddable Python SDK. Applications own the interface, business logic and deployment. The shipped runtime uses SQLite; no server, GUI, tenancy layer or cloud account is required.
+
+The execution path is application -> SDK -> optional Archon -> task -> Harness -> router -> context/reasoning -> provider -> policy/tools -> result. Archon schedules Harness calls and never invokes a provider. Harness executes one task and never decomposes it. Critical transitions use explicit calls and database transactions. Events only report transitions.
+
+SQLite stores runs, tasks, attempts, sessions, calls, tool intents/results, approvals, checkpoints, reservations and ordered events. State and corresponding events are written together. Executor leases prevent competing drivers. A confirmed model response is reusable after interruption. An ambiguous external side effect requires reconciliation. Pause preserves remaining plan funding; cancellation releases unused allocations and retains unresolved charges.
+
+Trace output is a separate append-only diagnostic projection, with credential redaction and opt-in payload capture. Runtime checkpoints necessarily retain conversation and tool data for recovery; turning off trace payload capture does not remove durable state.
+
+Routing applies hard capability, locality, provider, context and budget constraints before deterministic Nano/Core/Apex ranking. Catalog snapshots retain unknown fields, timestamps, price provenance and failed-refresh evidence. Discovery never enables a deployment. Strict financial admission rejects unknown or unbounded prices.
+
+Archon validates a topologically ordered graph of at most eight nodes and uses at most two concurrent workers. Applications register agents by role/name. Planner, reviewer, corrector and assembler roles may be supplied in that registry. Assembly is tool-free and executes through Harness, followed by deterministic final checks. The default includes review and one correction cycle. Setting orchestration.review='effort' permits a simple executor path while Pro/Deep retain independent review. Optional passes cannot remove required criteria.
+
+Preflight persists the graph, selected deployments, capability/price evidence, consumed work and bounded phase envelopes before dispatch. Atomic funding transfers into individual reservations without double counting. One least-cost eligible alternative is evaluated if the preferred plan does not fit. Resume retains completed work and revalidates remaining funding against current metadata and narrowed authority.
+
+General graphs require no Git repository. The explicitly selected coding strategy uses isolated writer worktrees, a baseline snapshot and one integration workspace. Original edits and selected untracked files are preserved. Applying patches to the original checkout, committing, pushing and publishing are separate application decisions.
+
+Built-ins provide workspace file I/O, exact allow-listed test commands, bounded HTTP GET against declared origins, artifacts and policy-gated memory tools. There is no unrestricted shell. Trusted test programs and application-supplied Python tools still use their host account's privileges.
+
+First-party memory stores documents, deterministic chunks, vectors, episodic/semantic records, metadata and run/task links in SQLite. Retrieval combines FTS5 and optional cosine ranks. Context includes bounded untrusted excerpts and exact source hashes. Retrieved content cannot authorize writes or change policy.