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).

