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.

# 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. 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 and the runnable example.

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.