# harsh-life/hypermind-intelligence architecture

> Architecture diagram of the GitHub repository harsh-life/hypermind-intelligence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsh-life/hypermind-intelligence
- Repository: https://github.com/harsh-life/hypermind-intelligence

## Overview

The tree describes a Python intelligence framework with registries, model inference, orchestration, policy enforcement, execution, and evaluation. The likely user-facing flow is a request handled by the orchestrator, which can propose actions and use model inference, policies, and execution before producing a run artifact; evaluation provides a separate assessment capability. The README is only a title, and the orchestration and evaluation implementations were not sampled, so links involving those areas are omitted rather than inferred. Dashed links mark documented optional wiring.

Main entry points: [`trackA/schemas/workers.py`](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/workers.py) (Worker contracts), [`trackA/models/runtime.py`](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/models/runtime.py) (Inference dispatch), [`trackA/registries/workers.py`](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/workers.py) (Worker registry), [`trackA/orchestrator/run.py`](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/run.py) (Run orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_coordination["Orchestration"]
  node_orchestrator["Run orchestration<br/>[run.py]"]
  node_action["Action proposals<br/>[orchestrator.py]"]
  node_run_artifact["Run artifacts<br/>[run_artifact.py]"]
  node_run_storage[("Artifact persistence<br/>[storage.py]")]
end

subgraph group_inference["Model Inference"]
  node_runtime_registry["Inference dispatch<br/>[runtime.py]"]
  node_inference_adapter["Backend adapter<br/>[runtime.py]"]
end

subgraph group_governance["Registries and Policy"]
  node_policy_engine["Policy engine<br/>[engine.py]"]
  node_scope_gate["Scope gate<br/>[scope_gate.py]"]
  node_registries[("Manifest registries<br/>[_store.py]")]
  node_worker_registry["Worker registry<br/>[workers.py]"]
  node_model_registry["Model registry<br/>[models.py]"]
  node_skill_registry["Skill registry<br/>[skills.py]"]
  node_tool_registry["Tool registry<br/>[tools.py]"]
  node_role_resolver["Role resolution<br/>[resolution.py]"]
end

subgraph group_runtime["Execution and Evaluation"]
  node_execution["Tool execution<br/>[tools.py]"]
  node_execution_backends["Execution backends<br/>[backends.py]"]
  node_evaluation_harness["Evaluation harness<br/>[harness.py]"]
  node_evaluation_cases["Evaluation cases<br/>[cases.py]"]
  node_evaluation_judge["Evaluation judge<br/>[judge.py]"]
  node_evaluation_results["Evaluation results<br/>[results.py]"]
  node_evaluation_storage[("Evaluation storage<br/>[storage.py]")]
end

subgraph group_contracts["Schemas"]
  node_base_schemas["Base schemas<br/>[base.py]"]
  node_common_schemas["Common schemas<br/>[common.py]"]
  node_worker_schemas["Worker contracts<br/>[workers.py]"]
  node_schema_catalog["Domain schemas"]
end

node_user(("Framework caller"))

node_runtime_registry -->|"dispatches to"| node_inference_adapter
node_runtime_registry -.->|"optionally validates"| node_model_registry
node_worker_registry -->|"delegates to"| node_registries
node_worker_registry -->|"validates manifests"| node_worker_schemas
node_policy_engine -->|"models decisions"| node_base_schemas
node_run_storage -->|"reads and writes"| node_run_artifact
node_worker_schemas -->|"inherits from"| node_base_schemas
node_worker_schemas -->|"uses types"| node_common_schemas
node_user -.->|"initiates run"| node_orchestrator
node_orchestrator -.->|"proposes actions"| node_action

click node_orchestrator "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/run.py"
click node_action "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/orchestrator.py"
click node_run_artifact "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/run_artifact.py"
click node_run_storage "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/storage.py"
click node_policy_engine "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/policy/engine.py"
click node_scope_gate "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/policy/scope_gate.py"
click node_registries "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/_store.py"
click node_worker_registry "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/workers.py"
click node_model_registry "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/models.py"
click node_skill_registry "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/skills.py"
click node_tool_registry "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/tools.py"
click node_role_resolver "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/resolution.py"
click node_runtime_registry "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/models/runtime.py"
click node_inference_adapter "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/models/runtime.py"
click node_execution "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/execution/tools.py"
click node_execution_backends "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/execution/backends.py"
click node_evaluation_harness "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/harness.py"
click node_evaluation_cases "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/cases.py"
click node_evaluation_judge "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/judge.py"
click node_evaluation_results "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/results.py"
click node_evaluation_storage "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/storage.py"
click node_base_schemas "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/base.py"
click node_common_schemas "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/common.py"
click node_worker_schemas "https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/workers.py"
click node_schema_catalog "https://github.com/harsh-life/hypermind-intelligence/tree/main/trackA/schemas"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_orchestrator,node_action,node_run_artifact,node_run_storage toneBlue
class node_runtime_registry,node_inference_adapter toneAmber
class node_policy_engine,node_scope_gate,node_registries,node_worker_registry,node_model_registry,node_skill_registry,node_tool_registry,node_role_resolver toneMint
class node_execution,node_execution_backends,node_evaluation_harness,node_evaluation_cases,node_evaluation_judge,node_evaluation_results,node_evaluation_storage toneRose
class node_base_schemas,node_common_schemas,node_worker_schemas,node_schema_catalog,node_user toneIndigo
```

## Components

### Orchestration

- [Run orchestration](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/run.py): `trackA/orchestrator/run.py`
- [Action proposals](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/orchestrator.py): `trackA/schemas/orchestrator.py`
- [Run artifacts](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/run_artifact.py): `trackA/orchestrator/run_artifact.py`
- [Artifact persistence](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/orchestrator/storage.py): `trackA/orchestrator/storage.py`

### Model Inference

- [Inference dispatch](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/models/runtime.py): `trackA/models/runtime.py`
- [Backend adapter](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/models/runtime.py): `trackA/models/runtime.py`

### Registries and Policy

- [Policy engine](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/policy/engine.py): `trackA/policy/engine.py`
- [Scope gate](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/policy/scope_gate.py): `trackA/policy/scope_gate.py`
- [Manifest registries](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/_store.py): `trackA/registries/_store.py`
- [Worker registry](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/workers.py): `trackA/registries/workers.py`
- [Model registry](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/models.py): `trackA/registries/models.py`
- [Skill registry](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/skills.py): `trackA/registries/skills.py`
- [Tool registry](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/tools.py): `trackA/registries/tools.py`
- [Role resolution](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/registries/resolution.py): `trackA/registries/resolution.py`

### Execution and Evaluation

- [Tool execution](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/execution/tools.py): `trackA/execution/tools.py`
- [Execution backends](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/execution/backends.py): `trackA/execution/backends.py`
- [Evaluation harness](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/harness.py): `trackA/evaluation/harness.py`
- [Evaluation cases](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/cases.py): `trackA/evaluation/cases.py`
- [Evaluation judge](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/judge.py): `trackA/evaluation/judge.py`
- [Evaluation results](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/results.py): `trackA/evaluation/results.py`
- [Evaluation storage](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/evaluation/storage.py): `trackA/evaluation/storage.py`

### Schemas

- [Base schemas](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/base.py): `trackA/schemas/base.py`
- [Common schemas](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/common.py): `trackA/schemas/common.py`
- [Worker contracts](https://github.com/harsh-life/hypermind-intelligence/blob/main/trackA/schemas/workers.py): `trackA/schemas/workers.py`
- [Domain schemas](https://github.com/harsh-life/hypermind-intelligence/tree/main/trackA/schemas): `trackA/schemas`

### Other components

- **Framework caller**

## Connections

- Inference dispatch → Backend adapter: dispatches to (evidence: `trackA/models/runtime.py`)
- Inference dispatch → Model registry: optionally validates (evidence: `trackA/models/runtime.py`)
- Worker registry → Manifest registries: delegates to (evidence: `trackA/registries/workers.py`)
- Worker registry → Worker contracts: validates manifests (evidence: `trackA/registries/workers.py`)
- Policy engine → Base schemas: models decisions (evidence: `trackA/policy/engine.py`)
- Artifact persistence → Run artifacts: reads and writes (evidence: `trackA/orchestrator/storage.py`)
- Worker contracts → Base schemas: inherits from (evidence: `trackA/schemas/workers.py`)
- Worker contracts → Common schemas: uses types (evidence: `trackA/schemas/workers.py`)
- Framework caller → Run orchestration: initiates run
- Run orchestration → Action proposals: proposes actions
