Intergrax

Python 3.12 Quick start Harness AI Docs LLM context LKW proof

Agent OS and Harness AI runtime for building, orchestrating, experimenting with, and validating specialized AI agents — with a clear separation between who decides, who executes, and who orchestrates.

First time evaluating? Start with Quick start (lab host, ~5 min). Next step: LKW Platform Proof (Docker + Elasticsearch + Kibana). Prerequisites: Python 3.12 · uv · Git


See Intergrax running

Two evaluation paths — start with the lighter lab path, then run the full product proof when ready.

Path Best for Requires
Quick start First contact — clone, verify, lab run, trace inspect uv sync, lab host on :8090
LKW Platform Proof Full Tier-3 product proof — RAG, observability export, Elasticsearch, Kibana Docker Compose, prerequisites above

Quick start runs the lab host and a traced Echo capability run. LKW platform proof validates a real run_id, tool_requested / tool_completed events, duplicate-free export, and safety-checked observability documents.

Overview

  • What: Intergrax is a Harness AI platform — the durable runtime that runs many agents, not a single chatbot or domain bot.
  • What it provides: Nexus Agent OS, Tier-0 catalogs (197 integrations · 200 tools · 150 skills in 42 bundles), LLM, RAG, memory, Ephemeral Code Craft (Done ECC-0…ECC-6), policy, trace, multi-agent graphs, and Tier-3 application hosts.
  • Who it is for: Teams building governed multi-agent systems — platform engineers, agent architects, Harness AI researchers, and product teams shipping agent-backed applications.
  • Why it is different: The Harness is the product; agents are replaceable. Agents own domain decisions inside a typed session loop; the harness owns policy, trace, and execution; Nexus owns multi-agent orchestration; applications own environment, identity, and production gates — without collapsing these into one mega-class.
  • Problem it solves: Stop rebuilding infrastructure for every new agent. Target: idea → first traced Nexus run in under one hour, then the same agent class moving from lab evaluation toward governed deployment paths when explicitly permitted.
Intergrax — Harness AI

┌──────────────────────────────────────────┐
│ Tier-3 Application environment           │
│ identity · profiles · org policy         │
│ AgentBinding · production scoreboard     │
└─────────────────────┬────────────────────┘
                      │ Task
┌─────────────────────▼────────────────────┐
│ Tier-1 NexusLoop (Agent OS)              │
│ graphs · capability routing · HITL       │
└─────────────────────┬────────────────────┘
                      │ one agent node → Agent.run()
┌─────────────────────▼────────────────────┐
│ Tier-2 Agent session                     │
│ HarnessKernel                            │
│ on_next_step · policy · trace · state    │
│ budgets                                  │
└─────────────────────┬────────────────────┘
                      │
┌─────────────────────▼────────────────────┐
│ Tier-0 Platform                          │
│ Integration → Tool → Skill → LLM · RAG   │
│ Memory                                   │
└──────────────────────────────────────────┘

Strategic direction: Development Strategy · System invariants · Ideal target: IDEAL_HARNESS_AI_ARCHITECTURE.md · Agent model canon: AGENT_CONTRACTS_AND_ASSEMBLY.md §13–§40


Table of contents


Current platform maturity

Harness baseline: 32/32 audit layers at L3 (scorecard · IDEAL_HARNESS_L3 · audit map §5 · Maturity Taxonomy).

Maturity uses L0–L4 levels (not arbitrary percentages) — navigation summaries in this README. Authoritative readiness claims use the four-axis A/I/P/E vocabulary in MATURITY_TAXONOMY.md. Per-domain evidence lives in domain-layer pairs: docs/architecture/<DOMAIN>.mddocs/plan/<DOMAIN>.md. Cross-layer capabilities use multi-layer feature pairs: docs/features/architecture/<FEATURE>.mddocs/features/plan/<FEATURE>.md — see Multi-layer feature docs.

Area Maturity Evidence / open gap
Agent contracts (ACP) L3 Phase ACP Done · fleet on_next_step migration ongoing
Tools L3 TOOL-ENG closeout Done · deferred: hierarchical LLM category pass
Tier-3 hosts L3 (depth partial) APP-PROD gates Done · §22 profile bundles M1–M3 Done · enterprise distribution P4
Memory L3 MEM / MEM-VEC / MEM-DEPTH Done · L3 harness · P2 depth: procedural store, org LTM parity, per-step budget caps before CE collect
RAG L3 (profile-driven) M-RAG-DEPTH / GRAPH Done · Tier-3 RagProfile required · autonomous parser/chunker/retriever selection Frozen/P4 → AHI
Adaptive harness (AHI) L4-ready (mechanisms) W-ADAPT Done · L4 runtime mechanisms implemented · production L4 evidence requires product-host run volume

Also at L3: LLM adapters · Observability · Nexus flow · UAEP · Skills · Integrations — full index in architecture hub.


License and collaboration model

Intergrax is public and source-available for evaluation and technical partner discovery. It is not distributed under an open-source license. Production, commercial, and redistribution use require explicit permission from the copyright holder.

External feedback, proof-path testing, integration proposals, and design-partner discussions are welcome under the collaboration model described in COLLABORATION.md. Full terms: LICENSE.

Active public feedback paths are listed in the Public Issue Index. Use it to choose the right curated issue for proof-path feedback, documentation clarity, integration feedback, or design-partner interest.


Public Discussion Map

The open GitHub issues are not a generic implementation backlog. They are a maintainer-curated public discussion map for evaluating Intergrax as a Harness AI / Agent OS platform.

Use the Public Issue Index to choose the right entry point.

Track Use when you want to discuss
Proof path feedback First-run setup, README quick start, evidence and trace inspection
Architecture discussion Harness AI boundaries, Nexus as Agent OS, policy-first execution, agent contracts
Integration feedback Attestation, trace/evidence export, MCP-style controlled task surfaces
Product validation Legal review, research workflows, local knowledge workspace, lab application, assistant hub
Deep technical review Capability graph, evaluation gates, cost governance, reliability, security, observability, developer experience

Public discussion issues do not create support obligations, roadmap commitments, production-use permission, commercial-use permission, redistribution rights, derivative-work rights, SLA commitments, or security vulnerability handling. For security reports, use SECURITY.md. For commercial licensing, production use, partnerships, redistribution, derivative works, or substantial implementation permission, contact the maintainer directly.


Who this repository is for

Intergrax is currently most useful for technical readers evaluating how to build governed agent applications with explicit runtime boundaries, policy-controlled tool execution, trace/evidence surfaces, and external verification hooks.

It is especially relevant for:

  • AI platform engineers designing agent infrastructure beyond a single demo agent
  • Teams building governed agent applications that need policy, HITL, trace, evidence, or evaluation surfaces
  • Builders working on attestation, receipts, boundary events, auditability, observability, or agent governance
  • Developers evaluating Nexus orchestration, tool/skill boundaries, RAG, memory, and Tier-3 application hosts
  • Potential technical design partners willing to run proof paths and report friction

Intergrax is not presented as a finished SaaS, a general-purpose open-source framework, or a production certification claim. See COLLABORATION.md, ROADMAP.md, and LICENSE.


Start here

If you are… Start with
Evaluating Intergrax for the first time Quick start · LKW Platform Proof · EVALUATION_GUIDE.md · FAQ.md · Proof of platform
Checking use-case fit USE_CASES.md · EVALUATION_GUIDE.md
Checking collaboration or license boundaries COLLABORATION.md · LICENSE
Reviewing the Harness AI / Agent OS model INTERGRAX_HARNESS_NARRATIVE.md · AGENT_CREATION_GUIDE.md
Exploring attestation, boundary events, or external verification BOUNDARYATTEST_ATTESTATION_POC.md · attestation_demo README
Exploring product-validation directions LOCAL_KNOWLEDGE_WORKSPACE_ALPHA.md · USE_CASES.md
Interested in feedback, design-partner work, or integration proposals PARTNERS.md · COLLABORATION.md · Public Issue Index

Looking for common questions? See FAQ.md.

This navigation is intentionally public-facing; canonical technical architecture remains in the architecture and plan documents linked below.


The agent model — why architects choose Intergrax

Most agent frameworks mix planning, policy, tool I/O, and multi-agent routing into a single author-facing class. That works for demos; it breaks for governed products — opaque control flow, untyped state, and agents that secretly become mini operating systems.

Intergrax treats the agent as a domain decision unit running inside a rich, typed environment. Four roles stay explicit:

Layer Responsibility Answers
Application (Tier-3) Environment & product wiring Who is the tenant? Which tools/memory/RAG profile? Org policy? Production gates?
NexusLoop (Tier-1) Multi-agent orchestration Which agents run on this Task? Graph, HITL, checkpoints at task level?
Agent (Tier-2) Domain cognition per session What is the next move? Plan valid? Terminal? Pause for human? — via on_next_stepStepOutcome
HarnessKernel Deterministic harness cycle Policy allowed? State merged safely? Trace recorded? Budgets enforced?

Author mental model (one session, many steps):

result = await agent.run(AgentRunRequest(...))     # once per graph node (or direct in lab)

inside run():
    loop:
        state = load_session_state(step_ctx)       # READ  — typed AcpSessionState
        outcome = await on_next_step(step_ctx)     # DECIDE — StepOutcome factories
        HarnessKernel.execute_step(outcome, ...)   # EXECUTE — policy, trace, merge

What you get as a platform owner:

  • Readable agent code — reviewers see continue / complete / fail / HITL from the final return StepOutcome.*, not scattered flags in dicts.
  • Same agent, many deployments — lab vs legal vs research host = different ApplicationEnvironmentProfile, zero agent forks.
  • Virtual workforce ready — organizational policy envelope on the host, not if customer == acme in agent source.
  • Operational readiness is measurableAgent Production Readiness Scoreboard (contract, runtime, policy, observability, checkpointing, idempotency, security, evaluation, lifecycle, routing).
  • Agents are swappable — capability-based routing (research.web_search), not hardcoded class names in Nexus.

Canonical decisions: ADR-AGENT-001 (Nexus stays Agent OS) · ADR-AGENT-002 (Agent.run() facade) · ADR-AGENT-003 (step loop + dual observability).

Implementation status: architecture decision-complete (§13–§40); delivery via plan Phase ACP (typed contracts → step loop → fleet migration → prod gates). Today: UAEP bridge + Nexus path; target: typed on_next_step on all roster agents.

Deep dive: Agent Creation Guide — Appendix AC · Architecture hub — agent in environment


Why another AI framework?

Most AI projects ship one agent class that secretly is the whole stack — planner, executor, policy, and orchestrator in one file.

Intergrax ships the Harness — a governed Agent OS where agents decide domain steps, the kernel executes under policy, and Nexus orchestrates graphs — so you can field dozens of specialized agents and Tier-3 products on one platform without architectural collapse.

If you evaluate GitHub projects by “does the architecture scale beyond the demo?” — this separation is the answer.


Audience

This repository is for you if you are:

Role Why Intergrax
AI systems architect Four-tier Harness AI model; agent / kernel / Nexus split; policy-first execution; L0–L4 maturity
Agent platform engineer Typed Agent.run() + on_next_step, HarnessKernel, ToolRuntime, dual observability planes
Multi-agent runtime developer Delegation, subagents, parallel graphs, HITL — without nested OS forks
Harness AI researcher Lab workflow, trace inspection, evaluation hooks, adaptive harness (L4)
Product team shipping agents Tier-3 application shells — isolated deployable hosts composing Tier-2 agents

Not the primary audience: teams looking for a finished SaaS chatbot, a prompt library, or a no-code workflow builder.


Quick start

Goal: clone → install → verify → run → inspect.

Prerequisites

Python 3.12 · uv · Git

1. Install

git clone https://github.com/jakbuczarnecki/intergrax.git
cd intergrax
uv sync --extra dev

2. Verify

uv run intergrax doctor
uv run pytest -m gate -q

# Optional — core certification evidence
uv run intergrax certify core --level L2

# Optional — report-derived evidence timeline
uv run intergrax trace show
uv run intergrax trace export

trace show renders the report-derived timeline to stdout. trace export writes build/evidence/trace/timeline.json and timeline.md. This is deterministic mock evidence derived from the certification report, not live runtime tracing.

See Harness Environment — core certification.

3. Run the lab host

uv run uvicorn lab_application.host.main:app --host 127.0.0.1 --port 8090

4. Usage — execute and inspect

# Submit a run (Echo agent via capability routing)
curl -s -X POST http://127.0.0.1:8090/v1/lab/run \
  -H "Content-Type: application/json" \
  -d '{"message":"hello","capability":"echo.basic"}'

# Inspect trace — copy task_id from the POST response JSON above
curl -s "http://127.0.0.1:8090/debug/tasks/{task_id}/trace?include_runtime=true"

Expected output (abbreviated):

{"task_id":"01JABC…","run_id":"01JABC…","state":"completed","answer":"hello","agent_id":"echo"}
# trace excerpt (GET /debug/tasks/{task_id}/trace?include_runtime=true)
step_started → tool_requested → tool_completed → step_completed

Next steps: scaffold your own agent, register it, rerun through the lab, inspect /debug/tasks/{id}/metrics and /events.

Command Purpose
python -m intergrax.scaffold new-agent {name} --capability domain.action Create Tier-2 agent skeleton
python -m intergrax.scaffold new-application {name} --profile lab Create Tier-3 host
python -m intergrax.scaffold new-stack {name} Agent + application bundle
uv run intergrax run {module}:app Launch any ASGI application host
uv run intergrax certify core --level L2 Core certification report (deterministic mock contract evidence)
uv run intergrax trace show Render report-derived evidence timeline to stdout
uv run intergrax trace export Write timeline JSON/Markdown under build/evidence/trace/
python -m intergrax.debug Debug CLI

Full workflow: Agent Creation Guide · Contributing setup: CONTRIBUTING.md

After running the quick start, share structured feedback via #186 README quick start feedback or choose another path from the Public Issue Index.


Proof of platform

Live application proof: LKW Platform Proof — run a real Local Knowledge Workspace platform path with Docker Compose, Elasticsearch, Kibana, and duplicate/safety validation.

External narrative: Intergrax Harness Narrative

External integration proof: BoundaryAttest Attestation PoC — external validation of host-signed execution boundary events (technical integration validation, not production certification).

Product-validation direction: Local Knowledge Workspace alpha — product-validation narrative for local governed knowledge workflows (alpha track, not a finished product or SaaS).

What is it? The fastest local way to verify Intergrax as an evidence-backed harness platform — not a production readiness or compliance claim.

Why run it? You get a repeatable, offline proof that the harness can produce and aggregate the core evidence surfaces an early adopter needs to trust the platform locally. The A2 end-to-end evidence smoke audit verified this exact command sequence on a clean local run.

Run the canonical proof path:

uv run intergrax certify core --level L2
uv run intergrax trace export
uv run intergrax evidence live-core
uv run intergrax evidence eval
uv run intergrax evidence cost
uv run intergrax evidence posture
uv run intergrax evidence posture export

All artifacts land under build/evidence/:

Surface Artifacts
Core certification build/evidence/core_certification/report.json, build/evidence/core_certification/report.md
Trace evidence build/evidence/trace/timeline.json, build/evidence/trace/timeline.md
Live Tier-0 probes build/evidence/live_core_probes/live_core_report.json, build/evidence/live_core_probes/live_core_report.md
Eval evidence build/evidence/eval/report.json, build/evidence/eval/report.md
Cost evidence build/evidence/cost/report.json, build/evidence/cost/report.md
Evidence posture build/evidence/posture/posture.json, build/evidence/posture/posture.md

What this proves — local ability to produce and aggregate:

  • core certification evidence
  • trace evidence
  • selected local live Tier-0 probe evidence
  • eval regression evidence
  • cost evidence
  • evidence posture scoreboard

What this does not prove:

  • production runtime certification
  • security/compliance attestation
  • real provider execution
  • real LLM evaluation
  • billing
  • provider pricing
  • cloud cost estimation
  • product-specific acceptance

Verify artifacts and docs (after running the proof path):

python scripts/maintenance/check_evidence_artifacts.py

Confirms expected evidence artifacts exist and README still documents the canonical proof path.

Next steps: After the proof path, inspect build/evidence/posture/posture.md first, then drill into the individual evidence reports. For roadmap and status, see HARNESS_EVIDENCE_PACK.md. For architecture framing, see EXPERIMENTATION_AND_DEVELOPER_EXPERIENCE_production_gates.md.


What you can do today

Action How Learn more
Scaffold a new agent python -m intergrax.scaffold new-agent … Agent Creation Guide
Build a Tier-3 application new-application / new-stack applications/USAGE.md
Connect integrations IntegrationProfile + Tier-3 wiring architecture/INTEGRATIONS.md
Attach tools and skills ToolProfile, SkillProfile, skill_ids on contract architecture/TOOLS.md · architecture/SKILLS.md
Run through Nexus Lab or product host → NexusLoopAgent.run() / AgentEngine NEXUS_EXECUTION_FLOW.md · Agent model
Inspect traces /debug/tasks/{id}/trace, intergrax.debug HARNESS_ENVIRONMENT.md
Evaluate execution Evaluation profile, online registry, CVL hooks CRITIC_VERIFICATION.md
Ephemeral code craft Dynamic codegen loop in sandbox (Done ECC-0…ECC-6) CODE_CRAFT.md
Extend via plugins ToolPlugin, IntegrationPlugin, SkillPlugin EPs EXTENSION_AUTHOR_GUIDE.md

Reference hosts: applications/README.md · Reference agents: agents/README.md


Harness AI — the core idea

The future value is not in building one agent. The value is in building the runtime that allows many agents to be built, tested, and orchestrated quickly.

Intergrax implements the Harness AI chain:

Harness  →  Runtime (Nexus)  →  Agents  →  Applications  →  Products
Term Intergrax implementation
Harness Tier-1 Nexus + Tier-0 catalogs + Tier-3 wiring (policy, tools, integrations, trace)
Scaffold python -m intergrax.scaffoldnew-agent, new-application, new-stack, new-skill
Runnable agent instance Harness + agent + LLMProfile + resolved skill_ids / allowed_tools + RuntimePolicyBundle
Tool Atomic ToolContract — LLM/MCP invocable operation
Skill Composable SkillManifest — tools + prompts + policy fragment (not an LLM function)
Subagent Graph delegation via ExecutionGraph — not a nested OS
Policy PolicyEngine, budgets, HITL, RuntimePolicyBundle

Agent composition flow:

Application profile (Tier-3)  →  merge_environment  →  Agent.run(AgentRunRequest)
    → NexusLoop (multi-agent) or direct run (lab)
        → Agent.on_next_step  →  StepOutcome  (domain decides)
        → HarnessKernel       →  policy · trace · state merge (harness executes)
        → SkillManifest(s) · ToolRuntime.invoke  →  Integration adapters
        → LLM / RAG / memory gateways (per-step, policy-bound)

Vocabulary canon: architecture/PLATFORM_FOUNDATION.md §5.3 · Target model: IDEAL_HARNESS_AI_ARCHITECTURE.md


Laboratory vs production harness

Two modes on one codebase:

Mode Purpose Primary metric
Laboratory Fast hypothesis validation Idea → first traced run in under 1 hour
Production harness Governed Agent OS at organizational scale Stable integration paths + ops SLOs

New capabilities start in the lab (lab_application, pytest, debug API). Capabilities that ship to users graduate through maturity gates. Business agents (Phase K) require explicit product prioritization — default harness queue is gate maintenance.

Details: INTERGRAX_DEVELOPMENT_STRATEGY.md · HARNESS_ENVIRONMENT.md


Four-tier platform model

Tier-3  Applications     →  deployable products (legal API, lab host, research service)
Tier-2  Agents           →  specialized capability modules (LegalAgent, ResearchAgent)
Tier-1  Nexus Runtime    →  Agent OS (NexusLoop, AgentEngine, UAEP, governance)
Tier-0  Platform         →  universal building blocks (integrations, tools, skills, LLM, RAG)
Tier Role Path
Tier-0 — Platform Integrations, tools, skills, LLM, RAG, memory intergrax/ (outside Nexus orchestration)
Tier-1 — Nexus Task lifecycle, graphs, governance, event bus intergrax/runtime/
Tier-2 — Agents Domain logic: contracts, pipelines, prompts agents/
Tier-3 — Applications Isolated deployable environments applications/

Dependency rules:

intergrax/       MUST NOT import from agents/ or applications/
agents/          MUST NOT import from applications/
applications/    MAY import from agents/ and intergrax/

Agents consume Tier-0 through Nexus policy and ToolRuntime — never vendor SDKs directly. Tier-1/2/3 work is composition and wiring, not parallel platform mechanisms.

Canon: architecture/PLATFORM_FOUNDATION.md §5.2 · Hub: intergrax_runtime_architecture.md


Capability stack (Integration → Tool → Skill → Agent)

Layer What it is Invoked by LLM? Example
Integration Swappable backend contract No PostgreSQL, Bing, Jira REST
Tool Single atomic operation Yes rag.retrieve, jira.search_tasks
Skill Reusable pack: tool_ids + prompts + policy No legal.contract_review, harness.tool_smoke
Agent Domain module: contract + on_next_step / cognitive pattern, skill_ids[] LegalAgent in agents/legal/
Integration  →  Tool  →  Skill  →  Agent  →  Nexus (Harness)  →  Application wiring

Skills are not tools — the runtime resolves skills into allow-lists and instructions before the run.

Catalogs: INTEGRATIONS.md · TOOLS.md · SKILLS.md


Nexus runtime and agent execution

Nexus (Tier-1) is the Agent Operating System. It orchestrates Tasks and graphs — it is not the agent’s reasoning engine.

Component Role
NexusLoop Task intake, multi-agent graph, capability routing, HITL, application orchestration log
AgentRegistry Registration, capability tokens, skill/tool resolution, lifecycle gates
AgentEngine Bridge graph node → Agent.run() / session loop
HarnessKernel Per-step harness cycle — policy, trace, state merge, budgets (not domain planning)
ExecutionGraph Multi-agent workflows, delegation, parallel cap
ToolRuntime Unified tool gateway — policy, trace, idempotency (§42.12)
PolicyEngine Governance on tool/LLM/RAG/memory paths
ContextManager Context assembly, budget trimming, memory views

Target author API (ACP — canonical)

Agent.run(AgentRunRequest)  →  loop: on_next_step → StepOutcome  →  HarnessKernel.execute_step
  • One run() per graph node — many on_next_step inside the session.
  • Typed state (AcpSessionState) and typed outcomes — readability at code-review time.
  • Dual observability: AgentRunTrace (agent plane) + ApplicationRunSummary (orchestration plane).

UAEP (bridge today)

get_steps  →  run_step  →  decide_after_step   # maps to on_next_step + kernel during migration

All agents conform to the Unified Execution Runtime Specification (§42). Registration: AgentRegistry.register() — never fork NexusLoop for one agent.

Canon: AGENT_CONTRACTS_AND_ASSEMBLY.md · Plan: Phase ACP · UNIFIED_EXECUTION_RUNTIME.md · NEXUS_EXECUTION_FLOW.md · ORCHESTRATION.md §50–§54


Tier-0 catalog summary

Shipped first-party catalogs (verified via bootstrap_catalogs(integration_preset='full') + snapshot_catalogs()2026-06-23).

Integration  →  vendor backend (Postgres, Bing, Jira, …)
Tool         →  atomic LLM/MCP operation (rag.retrieve, websearch.query, …)
Skill        →  composable pack (tool_ids + prompts + policy fragment)
Layer Catalog size Module Architecture Plan Usage / authoring
Integrations 197 slugs · 31 contract categories (116 STABLE · 81 BETA) intergrax/integrations/ INTEGRATIONS.md plan/INTEGRATIONS.md Per-provider USAGE.md under intergrax/integrations/providers/
Tools 200 tool_ids · 49 bundles intergrax/tools/ TOOLS.md plan/TOOLS.md intergrax/tools/USAGE.md
Skills 150 skill_ids · 42 bundles intergrax/skills/ SKILLS.md plan/SKILLS.md Per-skill USAGE.md under intergrax/skills/providers/{bundle}/{skill_id}/

Control plane (profiles, wiring, resolver): AGENT_CREATION_GUIDE.md Appendix J · Extension plugins: EXTENSION_AUTHOR_GUIDE.md

Skill bundles (42): agent, billing, browser, cache, catalog, cloud_platform, code, codecraft, collaboration, context, cost, crm, data, dev, eval, filesystem, gitlab, graph, harness, health, hitl, http, identity, interaction, jira, knowledge, legal, memory, message_bus, metrics, ml, modality, notify, openai, ops, platform, rag, research, sandbox, storage, vector_store, workspace150 skills — full index in SKILLS.md.


Platform capabilities

Tier-0 building blocks — one canonical path per concern. Agents use these through Nexus; they do not reimplement them.

Concern Scale / module Documentation
Integrations 197 providers · intergrax/integrations/ architecture/INTEGRATIONS.md · [plan](https://github.com/jakbucza