Atmanatic Research

Apache-2.0 licensed Python reference implementation and protocol corpus for bounded, evidence-linked, reviewable research artifacts.

Atmanatic is a protocol and Python reference implementation for turning claims into bounded, evidence-linked, reviewable artifacts. It helps a research, compliance, audit, or agent workflow answer:

• What exactly is being claimed?
• What evidence supports it, and is that evidence admissible?
• What would falsify it?
• Did an independent reviewer challenge it?
• What was verified, in what scope, and when must it be revalidated?

The result is a replayable decision trail rather than an opaque confidence score. Invalid, stale, conflicting, self-reviewed, or authority-claiming artifacts fail closed. A successful validation never authorizes deployment, transactions, or execution.

Use It In A Workflow

proposal -> evidence -> challenge -> verification -> bounded validity -> human promotion

Atmanatic is useful when one person's, agent's, or service's output will become another system's input and the handoff needs durable provenance. Consumers keep their own models, storage, transport, credentials, and operational authority; Atmanatic supplies the contracts and gates at the boundary.

Example: audit a skill against a transcript

from pathlib import Path
from atmanatic_research import SkillManifest
from atmanatic_research.agent_skills import SkillRunStore

manifest = SkillManifest(
    name="quality-review",
    purpose="Validate output quality before release.",
    version="0.4.0",
    git_ref="main",
    output_directories=("runs", "logs"),
    expected_actions=("inspect evidence", "record finding"),
    model_profile="gpt-4o-mini",
)

store = SkillRunStore(Path("skill-store-demo"))
record = store.record_run(
    manifest,
    transcript="The agent inspected evidence and recorded the finding.",
    observed_actions=("inspect evidence", "record finding"),
    output_paths=("runs/quality-review.json", "logs/quality-review.log"),
)

print(record.audit_result.aligned)
print(record.audit_result.summary)

This creates a timestamped run directory, writes the persisted artifact JSON, and stores the aligned/misaligned audit metadata so the behavior of an agent can be reviewed over time.

The skill manifest, audit loop, schema, and CLI are reusable wheel capabilities. The registry, transcripts, run artifacts, logs, and generated outputs are consumer-local evaluation state. Atmanatic does not upload that state or automatically change a published skill version. Local audit evidence can inform a later, reviewed skill-version update released through the normal commit and CI gates.

Install From GitHub

Install the current repository revision directly:

python -m pip install git+https://github.com/heyooboob/Atmanatic-Research.git

For a release, prefer the wheel attached to the matching GitHub Release. The Protocol 0.1 conformance archive is available from CI as atmanatic-protocol-0.1-conformance.zip for consumers implementing the protocol in another language.

The source repository is now public. Install the released package from PyPI with python -m pip install atmanatic-research, and see docs/CONSUMER_GUIDE.md for integration levels, capability limits, reporting routes, and conformance guidance. Also see CONTRIBUTING.md for local checks and protocol change expectations, docs/LOCAL_PUBLIC_BOUNDARY.md for the local-to-public promotion boundary, and SECURITY.md for vulnerability reporting.

Alpha Status And Compatibility

The 0.1.x line is an alpha reference implementation. Its public compatibility surface is the released Python package, the Protocol 0.1 schemas and fixtures, the conformance archive, and the signed release manifest. The TypeScript implementation currently covers the published core fixture slice; source policy, evidence admission, orchestration, lifecycle, and graph-analysis implementations remain Python-focused.

Patch releases preserve documented behavior and machine-readable error codes where practical. Minor releases may add contracts, fields, or capabilities and may require explicit consumer migration. Consumers must pin a released version and must not depend on repository internals, untagged branches, or local runtime state. Alpha status means the protocol and APIs may still change before a stable 1.0 compatibility commitment.

First Validation

from atmanatic_research import validate_artifact_lineage

artifact = {
	"schema_version": 1,
	"artifact_id": "research-result-001",
	"parent_artifact_ids": [],
	"producer": "my-research-pipeline",
	"created_at": "2026-09-19T12:00:00Z",
	"content_hash": "a" * 64,
	"execution_authorized": False,
}

validated = validate_artifact_lineage(artifact)

Use the public validators to reject malformed or non-authorizing artifacts at your system boundary. Add evidence admission, independent review, verification results, and validity transitions as the workflow becomes decision-grade.

What Consumers Get

Important Boundary

This repository is not a hosted API, model provider, workflow engine, or execution system. It is the protocol core and reference implementation. A consumer can embed the package, run it in CI, exchange its JSON artifacts, or place an HTTP/event adapter around it without changing the protocol semantics.

Development happens in the local working tree. The tagged package, signed release assets, schemas, fixtures, and conformance materials are the public compatibility surface; see docs/LOCAL_PUBLIC_BOUNDARY.md for the promotion rules.

Start with the Protocol 0.1 draft, the conformance review package, or the architecture appendix. New consumers should also follow the consumer guide.

Atmanatic Protocol 0.1

The immediate standards-track milestone is Atmanatic Protocol 0.1, a vendor-neutral working draft for exchanging verifiable claims, evidence, and review outcomes between humans, AI agents, and software systems.

The protocol is broader than this Python package and narrower than an AI platform. It defines portable artifacts, validation semantics, review linkage, and bounded validity transitions. It does not define model providers, orchestration, storage, transport, or execution authority.

Architecture appendix

The project includes a grounded implementation appendix under docs/architecture/ covering:

• a layered architecture model for optimization, memory, verification, and authority;
• module-by-module invariants and rejection conditions;
• fail-closed and idempotent hardening standards;
• a test strategy for deterministic validation and replayability.

These materials are intended to complement the protocol and contract rules, not replace them. Optimization, memory continuity, and retrieval analysis may improve context quality and throughput, but they do not validate truth, substitute for evidence admission, or grant execution authority.

Build

python -m pip install build
python -m build

Test

python -m unittest discover -s tests -q

The project must build and test successfully with every external consumer repository absent.

Artifact contracts

The public package also validates common artifact lineage and verification envelopes:

from atmanatic_research import (
	validate_artifact_lineage,
	validate_verification_result,
	validate_review_outcome,
	validate_promotion_record,
)

These contracts require versioned identity, producer, timestamps, content hashes, explicit non-authority, and lifecycle metadata. Verification results record what a verifier checked; they do not establish universal truth or grant execution authority. Promotion records are explicit, scoped decisions and remain non-authorizing research artifacts.

validate_review_outcome() records the independent reviewer, the exact artifact hash under review, concrete challenge findings, and the disposition. A resolved outcome must include its resolution and cannot be authored by the same producer as the reviewed artifact.

Use advance_with_review() for transitions to independently_verified or awaiting_human_promotion. The packet must declare its SHA-256 content digest as metadata["content_hash"], and the validated review artifact's subject_artifact_hash must match it:

from atmanatic_research import ValidityLevel, advance_with_review

result = advance_with_review(
	packet,
	ValidityLevel.INDEPENDENTLY_VERIFIED,
	review_record,
)

Only a challenged_and_resolved review can advance the packet. Reviewer and challenge fields are derived from the artifact, and a failed transition leaves the packet unchanged. The standalone advance() remains the low-level validity protocol primitive; consumers enforcing Phase 2 governance should use the review-backed entry point for review-gated levels.

The provider-neutral run_referee_loop() accepts injected proposer/referee callables without adding an LLM or workflow dependency. Referee findings must be structured, unresolved findings block acceptance, revisions are bounded by max_revisions, unchanged revisions are rejected as non-progress, and malformed reviewer output fails closed.

Each referee finding declares review_purpose as one of falsifier, assumption_auditor, provenance_auditor, boundary_tester, or implementation_contract_reviewer. It must also include a non-empty, unique list of evidence_refs supporting the finding or its resolution. The resulting RefereeFinding preserves both fields as typed immutable values, so downstream audit code can distinguish reviewer roles and trace each disposition to its declared basis.

When findings require a revision, the reviser must return a proposal containing finding_responses. Every finding ID from that round must appear exactly once; each response declares addressed or disputed, a non-empty explanation, and supporting evidence references. Unknown, duplicate, omitted, or malformed responses fail closed. ReviewRound.responses preserves typed FindingResponse records. Adding responses without changing the proposal body still counts as non-progress and ends the loop without acceptance.

Untrusted proposer output can first pass through validate_proposal_envelope(). It returns an immutable typed ProposalEnvelope containing a schema version, proposal and parent identities, producer, timestamp, SHA-256 content digest, evidence references, tool versions, payload, and explicit non-authority:

from atmanatic_research import validate_proposal_envelope

proposal = validate_proposal_envelope({
	"schema_version": 1,
	"proposal_id": "proposal-1",
	"parent_proposal_id": None,
	"producer": "research-agent",
	"created_at": "2026-09-17T12:00:00Z",
	"content_hash": "a" * 64,
	"evidence_refs": ["evidence-1"],
	"tool_versions": {"research-agent": "1.2.0"},
	"payload": {"claim": "The bounded fixture passed."},
	"execution_authorized": False,
})

The envelope validates declared lineage and replay metadata; it does not recompute the payload hash or establish that cited evidence supports the proposal. Those checks belong to deterministic tooling and governed evidence admission.

Use run_enveloped_referee_loop() when every proposal and revision must satisfy that envelope contract. Reviewers receive typed ProposalEnvelope values. Each revision must use a new proposal_id, set parent_proposal_id to the immediately preceding proposal, change its payload and declared content hash, and include the required finding responses. Proposal IDs cannot be reused within a run. The returned rounds retain each full proposal and its finding IDs, providing a replayable proposal-to-critique-to-revision chain.

Both referee loops accept an optional caller-owned escalation_policy. It receives the current proposal and typed findings after each review round and returns escalation reasons when automated revision should stop. A non-empty result produces an EscalationRequest with status awaiting_human_review, the proposal snapshot, finding IDs, reviewer identities, and reasons. It always has execution_authorized=False; the external human workflow owns any subsequent decision. Malformed policy output and policy exceptions fail closed.

Non-progress detection covers the complete run, not only adjacent revisions. The generic loop rejects a proposal body that equals any earlier state. The envelope-aware loop separately rejects a payload that repeats under fresh proposal IDs or hashes. This prevents bounded retries from oscillating between previously rejected states while appearing to make progress.

Both loops also accept time_budget_seconds. They use a monotonic clock and check the budget before and after each reviewer and reviser callback. Exhaustion returns a rejected result with the last accepted proposal state. An optional clock callable supports deterministic tests. This is a cooperative budget: it detects an overrun after an external callback returns but cannot interrupt a blocked model or service call. Consumers must enforce hard per-call timeouts in their provider runtime.

build_orchestration_audit_events() projects a completed result into an ordered tuple of immutable OrchestrationAuditEvent records. The caller supplies a stable run_id; event IDs are derived deterministically as run_id:sequence. Events record completed reviews, finding responses, acceptance, rejection, or human escalation and always retain execution_authorized=False. The projection contains no generated timestamps or random identifiers, so replaying the same result and run ID produces the same event stream. Durable append-only storage, signatures, clocks, and delivery ordering remain consumer responsibilities.

For decision-grade evidence, use validate_and_admit_evidence() when the caller wants one fail-closed entry point. It first applies the complete evidence-card contract and then applies freshness, provenance, status, and recall admission checks.

Use require_claim_evidence() when a claim must be tied to those admitted cards. It rejects duplicate or conflicting evidence identifiers and rejects claim source references that are not present in the admitted evidence set.

Use validate_and_admit_governed_evidence() when evidence must also pass the institutional source registry before admission. It checks that every source is enabled, permitted for the card's agent, and meets the requested authority tier. Identified public sources additionally require a compliant request context and an acquisition receipt whose source and response hash match the evidence card:

from atmanatic_research import validate_and_admit_governed_evidence

validate_and_admit_governed_evidence(
	[cards[0]],
	registry,
	minimum_tier="A",
	request_contexts={
		"sec-edgar": {
			"identity_profile_id": "institutional-contact",
			"headers_present": ["User-Agent"],
		},
	},
	acquisition_receipts=[receipt],
)

Request contexts are keyed by source ID. Receipts are a list so separate retrievals from the same source can be linked by response content hash. The function returns the original cards only after source governance, complete card validation, and decision-grade admission all succeed.

Registries may also define per-agent evidence requirements:

registry["minimum_evidence"] = {
	"research-agent": {
		"minimum_sources": 2,
		"minimum_independent_sources": 2,
		"minimum_tier": "B",
	},
}
registry["sources"][0]["independence_group"] = "publisher-a"
registry["sources"][1]["independence_group"] = "publisher-b"

minimum_sources counts distinct source IDs. minimum_independent_sources counts distinct independence_group values, representing independently controlled publishers, custodians, or collection systems rather than merely different URLs. When more than one independent source is required, every contributing source must declare its group. A caller may request a stricter authority tier but cannot weaken the registry's minimum_tier.

Domain-specific evidence rules remain outside this package and can be injected as named validators. Each validator receives a copy of the validated evidence card and a tuple of its resolved source definitions. It returns no value or an empty iterable to pass, and non-empty rejection reasons to block admission:

def validate_sample_size(card, sources):
	if card["details"].get("sample_size", 0) < 30:
		return ["sample size is below 30"]
	return []

validate_and_admit_governed_evidence(
	cards,
	registry,
	domain_validators={"clinical-study": validate_sample_size},
)

Validator names appear in rejection messages for auditability. Malformed outputs and validator exceptions fail closed. The consumer owns the domain logic, versions, dependencies, and scientific adequacy of each validator.

Identified public sources

Public sources that require request identification can declare that policy without giving Atmanatic credentials, personal data, or responsibility for HTTP acquisition:

from atmanatic_research import assert_source_allowed, validate_acquisition_receipt

source = {
	"source_id": "sec-edgar",
	"authority_tier": "A",
	"enabled": True,
	"allowed_for": ["research-agent"],
	"access": {
		"policy_version": "1",
		"mode": "public_identified",
		"identity": {
			"mechanism": "header",
			"name": "User-Agent",
			"required": True,
			"profile_id": "institutional-contact",
		},
		"rate_limit": {"requests": 10, "period_seconds": 1},
	},
}
registry = {"sources": [source]}

assert_source_allowed(
	registry,
	"sec-edgar",
	"research-agent",
	request_context={
		"identity_profile_id": "institutional-contact",
		"headers_present": ["User-Agent"],
	},
)

The consumer resolves institutional-contact, performs the request, and may then call validate_acquisition_receipt() with a non-secret receipt containing the source ID, retrieval time, policy version, identity profile ID, compliance attestation, and response content hash. The receipt records declared policy compliance; it does not independently prove what headers were sent. Sources without an access policy retain the 0.1.0 behavior for compatibility.

Measurable falsifiers

Claims remain backward compatible and use qualitative falsifiers by default. When a domain permits measurement, declare falsifier_kind as measurable and provide the deterministic comparison condition:

claim = {
	"claim": "Source refresh latency remains below the decision window.",
	"source_ids": ["source-1"],
	"falsifier": "The p95 refresh latency exceeds 300 seconds over 24 hours.",
	"falsifier_kind": "measurable",
	"falsifier_measurement": {
		"metric": "source_refresh_latency_p95",
		"operator": ">",
		"threshold": 300,
		"unit": "seconds",
		"observation_window": "24 hours",
	},
	"counterclaim": "Burst load may cause refresh latency to exceed the window.",
	"uncertainty": "The observation excludes upstream outages.",
	"author": "research-agent",
	"independent_reviewer": "review-agent",
	"review_outcome": "challenged_and_resolved",
}

review_claim() validates the condition's structure. A domain validator, simulation, or human reviewer must still determine whether the named metric actually tests the claim and whether the threshold is appropriate.