### Installation and MCP Setup

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Instructions for installing Cruxible Core with MCP support and configuring the MCP server for AI agent integration.

```APIDOC
## Installation and MCP Setup

### Description
Install Cruxible Core with MCP support and configure it for AI agent integration.

### Installation

```bash
# Install with MCP support
pip install "cruxible-core[mcp]"

# Or using uv
uv tool install "cruxible-core[mcp]"
```

### MCP Server Configuration

Configure the MCP server in your AI agent's config file:

```json
{
  "mcpServers": {
    "cruxible": {
      "command": "cruxible-mcp",
      "env": {
        "CRUXIBLE_MODE": "admin"
      }
    }
  }
}
```
```

--------------------------------

### Install, Test, Lint, Format, and Type Check Dependencies (Bash)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/CLAUDE.md

This snippet provides bash commands for managing project dependencies and code quality. It includes commands for installing all extras, running tests (all or single files), linting with Ruff, formatting with Ruff, and type checking with Mypy.

```bash
# Install dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Run single test file
uv run pytest tests/test_config/test_schema.py -v

# Lint
uv run ruff check src tests

# Format
uv run ruff format src tests

# Type check
uv run mypy src
```

--------------------------------

### Install Cruxible Core with MCP

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/README.md

This command installs the Cruxible Core library along with the MCP (Multi-Client Protocol) tools. It is compatible with pip and uv package managers.

```bash
pip install "cruxible-core[mcp]"
```

```bash
uv tool install "cruxible-core[mcp]"
```

--------------------------------

### Execute Cruxible Workflow Prompt (Python)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

This snippet shows how to invoke a guided workflow prompt within Cruxible using Python. It demonstrates calling the 'onboard_domain' prompt with specific arguments. The function returns instructions or executes a predefined workflow.

```python
cruxible_prompt("onboard_domain", {"domain": "drug interactions"})
```

--------------------------------

### Cruxible Configuration: Constraints

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Details the format and usage of constraints in Cruxible. Explains the rule format, severity levels (warning/error), and clarifies that constraints are evaluated by `cruxible_evaluate` rather than during data ingestion.

```yaml
constraints:
  - name: ConsistentUserStatus
    rule: "User.FROM.status == User.TO.status"
    description: "Ensures related user entities have the same status."
    severity: "warning" # Use 'error' for critical violations
    entity_type: User # Optional: scope constraint to a specific entity type

  - name: HighConfidenceInferenceSource
    rule: "AI_INFERRED_REL.confidence > 0.9"
    description: "Flags inferred relationships with low confidence."
    severity: "error"
```

--------------------------------

### Cruxible Configuration: Named Queries

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Provides guidance on authoring named queries in Cruxible. Emphasizes keeping traversals focused, using filters to narrow results, and employing constraints for runtime parameter binding.

```yaml
named_queries:
  - name: FindHighValueCustomers
    description: "Finds customers who have made purchases above a certain amount."
    traversal:
      start_node: User
      steps:
        - relationship: PURCHASED
          direction: outgoing
          filter: "timestamp > $start_date"
        - node: Product
          filter: "price > $min_price"
    parameters:
      - name: start_date
        type: datetime
      - name: min_price
        type: float
```

--------------------------------

### Initialize and Query Cruxible Graph (Bash)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

This snippet demonstrates how to initialize a Cruxible graph from a directory and execute named queries. It requires the `cruxible-mcp` to be configured and assumes a pre-built graph is present. The output will be the result of the executed queries.

```bash
cd demos/drug-interactions
# The .mcp.json here configures cruxible-mcp automatically

1. cruxible_init(root_dir=".")                          # loads existing graph
2. cruxible_query("check_interactions", params={"drug_id": "warfarin"})
3. cruxible_query("enzyme_impact", params={"drug_id": "fluoxetine"})
```

--------------------------------

### List Cruxible Prompts

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Lists all available workflow prompts, including their descriptions and required arguments. This command helps users discover available guided workflows.

```bash
cruxible prompt list
```

--------------------------------

### Clone Cruxible Core Demo

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/README.md

This command clones the Cruxible Core repository to access demo projects. It specifically targets the drug interactions demo, which includes a configuration, prebuilt graph, and MCP setup.

```bash
git clone https://github.com/cruxible-ai/cruxible-core
cd cruxible-core/demos/drug-interactions
```

--------------------------------

### Initialize Cruxible Instance

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Validates the configuration file and initializes the Cruxible instance. The instance_id generated is crucial for all subsequent operations.

```python
1. cruxible_validate(config_path="config.yaml")
2. cruxible_init(root_dir=".", config_path="config.yaml")
3. Save the instance_id for all subsequent calls
```

--------------------------------

### Feedback-to-Constraint Workflow in Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

This workflow outlines how to convert rejection patterns observed in feedback into actionable constraints. It involves identifying rejected edges, analyzing entity properties, and proposing a new constraint rule.

```python
from cruxible import cruxible_list, cruxible_get_entity, cruxible_add_constraint, cruxible_evaluate

# Assume target_relationship and target_entity_type are defined
target_relationship = "some_relationship"
target_entity_type = "some_entity"

# 1. List feedback records and filter for rejections
feedback_records = cruxible_list(resource_type="feedback")
rejected_edges = [f for f in feedback_records if f.get('action') == 'reject' and f.get('relationship') == target_relationship]

# Store property mismatches for rejected edges
mismatches = []

# 2. For each rejected edge, look up source and target entity properties
for edge in rejected_edges:
    source_id = edge['source_id']
    target_id = edge['target_id']

    source_entity = cruxible_get_entity(entity_type=target_entity_type, entity_id=source_id)
    target_entity = cruxible_get_entity(entity_type=target_entity_type, entity_id=target_id)

    # 3. Compare rejected edges — look for shared property mismatches
    # This is a simplified example; a real implementation would compare specific properties
    if source_entity and target_entity:
        # Example: Check if a specific property differs
        if source_entity.get('property_A') != target_entity.get('property_A'):
            mismatches.append({'source_prop': source_entity.get('property_A'), 'target_prop': target_entity.get('property_A')})

# 4. If a pattern is strong (e.g., 5+ rejections with similar mismatches), propose a constraint
if len(mismatches) >= 5: # Example threshold
    # Determine the rule expression based on observed mismatches
    # This requires logic to generalize the pattern
    rule_expression = f"{target_relationship}.FROM.property_A == {target_relationship}.TO.property_A"
    print(f"Proposing constraint: {rule_expression}")

    # 5. Call cruxible_add_constraint with the rule expression
    constraint_id = cruxible_add_constraint(rule=rule_expression, severity="warning")
    print(f"Added constraint with ID: {constraint_id}")

    # 6. Run cruxible_evaluate to verify the new constraint
    evaluation_results = cruxible_evaluate()
    print("Re-evaluated graph with new constraint.")
    # Further analysis of evaluation_results to check for expected violations
else:
    print("No strong rejection pattern found to create a constraint.")
```

--------------------------------

### Find Candidates via CLI

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

A command-line tool to find potential relationship candidates within the graph. This example demonstrates using the 'shared_neighbors' strategy to identify drugs that share common enzyme metabolisms.

```bash
cruxible find-candidates --relationship interacts_with \
  --strategy shared_neighbors \
  --via metabolized_by
# [table of candidate drug pairs sharing enzymes]
# 15 candidate(s) found.
```

--------------------------------

### GET /cruxible_sample

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/mcp-tools.md

Returns a sample of entities for quick data inspection, based on entity type and an optional limit.

```APIDOC
## GET /cruxible_sample

### Description
Retrieves a sample of entities for quick data inspection. This endpoint is useful for understanding the data structure and content of a specific entity type.

### Method
GET

### Endpoint
/cruxible_sample

### Parameters
#### Query Parameters
- **instance_id** (string) - Required - Instance ID
- **entity_type** (string) - Required - Entity type to sample
- **limit** (int) - Optional - Max entities (default: 5)

### Request Example
```json
{
  "instance_id": "your_instance_id",
  "entity_type": "Person",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **entities** (list[dict]) - Sampled entity records
- **entity_type** (string) - Entity type sampled
- **count** (int) - Number returned

#### Response Example
```json
{
  "entities": [
    {
      "id": "person_123",
      "name": "Alice"
    }
  ],
  "entity_type": "Person",
  "count": 1
}
```
```

--------------------------------

### Auditing Decisions with Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

This workflow details how to audit a decision by locating the relevant query run, retrieving traversal evidence, and examining associated feedback and outcomes. This is crucial for understanding the data supporting a decision.

```python
from cruxible import cruxible_list, cruxible_receipt

# Locate the query run for receipts
receipts = cruxible_list(resource_type="receipts")
if receipts:
    # Assuming we are interested in the first receipt found
    target_receipt_id = receipts[0]['id']
    print(f"Auditing receipt ID: {target_receipt_id}")

    # Get traversal evidence for the receipt
    evidence = cruxible_receipt(receipt_id=target_receipt_id)
    print(f"Traversal evidence: {evidence}")

    # See feedback related to this receipt
    feedback = cruxible_list(resource_type="feedback", receipt_id=target_receipt_id)
    print(f"Feedback found: {len(feedback)}")

    # See outcomes related to this receipt
    outcomes = cruxible_list(resource_type="outcomes", receipt_id=target_receipt_id)
    print(f"Outcomes found: {len(outcomes)}")
else:
    print("No receipts found to audit.")
```

--------------------------------

### Debug Cruxible Query Workflow

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

A step-by-step process for debugging issues encountered when running queries. It involves schema verification, data sampling, query execution, and trace inspection.

```python
1. cruxible_schema(instance_id)
2. cruxible_sample(instance_id, "entry_point_entity_type")
3. cruxible_query(instance_id, "query_name", params={...})
4. cruxible_receipt(receipt_id)
```

--------------------------------

### Cruxible Configuration: Ingestion Mappings

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Explains how to set up ingestion mappings for data sources in Cruxible. It covers mapping CSV columns to property names using `column_map` and suggests using `cruxible_add_relationship` for inferred relationships instead of batch CSV production.

```yaml
ingestion_mappings:
  - type: entity
    entity_type: Product
    data_source: "s3://my-bucket/products.csv"
    column_map:
      "product_id_csv": "id"
      "product_name": "name"
      "price_usd": "price"

  - type: relationship
    relationship_name: PURCHASED
    data_source: "s3://my-bucket/purchases.csv"
    column_map:
      "buyer_user_id": "from_id"
      "seller_user_id": "to_id"
      "purchase_date": "timestamp"
    # For inferred relationships, it's recommended to use cruxible_add_relationship directly.
```

--------------------------------

### Define Domain in YAML

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/README.md

This snippet shows how to define entity types, properties, and relationships for a decision domain using YAML. It also includes an example of a named query for suggesting alternatives based on domain definitions.

```yaml
entity_types:
  Drug:
    properties:
      drug_id: { type: string, primary_key: true }
      name:    { type: string }
  Enzyme:
    properties:
      enzyme_id: { type: string, primary_key: true }
      name:      { type: string }

relationships:
  - name: same_class
    from: Drug
    to: Drug
  - name: metabolized_by
    from: Drug
    to: Enzyme

named_queries:
  suggest_alternative:
    entry_point: Drug
    returns: Drug
    traversal:
      - relationship: same_class
        direction: both
      - relationship: metabolized_by
        direction: outgoing
```

--------------------------------

### Full Drug Interactions Demo Configuration

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/config-reference.md

A complete example of a Cruxible Core configuration file for the drug-interactions demo. It showcases the definition of entity types, relationships, named queries, constraints, and ingestion settings.

```YAML
name: drug_interactions_demo
description: >
  Clinical drug interaction graph. 46 drugs across 6 therapeutic
  classes plus 6 CYP450 enzymes.

entity_types:
  Drug:
    description: A pharmaceutical drug from DDinter and/or CYP450 datasets.
    properties:
      drug_id:
        type: string
        primary_key: true
        description: Lowercase normalized drug name
      name:
        type: string
        description: Display name of the drug
      atc_code:
        type: string
        optional: true
        description: ATC level-1 code(s)
      therapeutic_class:
        type: string
        optional: true

  Enzyme:
    description: A CYP450 metabolic enzyme that processes drugs.
    properties:
      enzyme_id:
        type: string
        primary_key: true
        description: Enzyme identifier (e.g. cyp3a4)
      name:
        type: string
        description: Standard enzyme name (e.g. CYP3A4)
      family:
        type: string
        description: Enzyme family (CYP450)

relationships:
  - name: interacts_with
    description: Known drug-drug interaction from DDinter database.
    from: Drug
    to: Drug
    cardinality: many
    properties:
      severity:
        type: string
        description: Interaction severity (Major/Moderate/Minor/Unknown)

  - name: metabolized_by
    description: Drug is a substrate of this CYP450 enzyme.
    from: Drug
    to: Enzyme
    cardinality: many
    properties:
      source:
        type: string
        description: Data source for this relationship

  - name: inhibits
    description: Drug inhibits this CYP450 enzyme (AI-inferred).
    from: Drug
    to: Enzyme
    cardinality: many
    properties:
      confidence:
        type: float
        description: Confidence score 0.0-1.0
      evidence:
        type: string
      source:
        type: string

  - name: same_class
    description: Two drugs in the same therapeutic class.
    from: Drug
    to: Drug
    cardinality: many
    properties:
      therapeutic_class:
        type: string

named_queries:
  check_interactions:
    description: "What drugs interact with this one, and how severe?"
    entry_point: Drug
    returns: Drug
    traversal:
      - relationship: interacts_with
        direction: both

  find_mechanism:
    description: "Why do these two drugs interact? Trace through shared enzymes."
    entry_point: Drug
    returns: Drug
    traversal:
      - relationship: metabolized_by
        direction: outgoing
      - relationship: metabolized_by
        direction: incoming

  suggest_alternative:
    description: "Find drugs in the same class metabolized by different enzymes."
    entry_point: Drug
    returns: Drug
    traversal:
      - relationship: same_class
        direction: both
      - relationship: metabolized_by
        direction: outgoing

constraints:
  - name: no_self_interaction
    description: A drug should not interact with itself.
    rule: "interacts_with.FROM.drug_id != interacts_with.TO.drug_id"
    severity: error

ingestion:
  drugs:
    description: Drug entities from combined DDinter + CYP450 dataset
    entity_type: Drug
    id_column: drug_id
  enzymes:
    description: CYP450 enzyme entities
    entity_type: Enzyme
    id_column: enzyme_id
  interactions:
    description: Drug-drug interactions from DDinter
    relationship_type: interacts_with
    from_column: drug_id_a
    to_column: drug_id_b

```

--------------------------------

### Provide Feedback on Graph Edges

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Allows users to provide feedback on specific graph edges, enabling iterative improvement of the graph's accuracy and intelligence. Feedback can be sourced from AI reviews or human judgments.

```python
# Provide feedback on an edge
cruxible_feedback(instance_id, receipt_id, edge_id, "approve", source="ai_review")

# Record end-to-end correctness
cruxible_outcome(instance_id, "success")
```

--------------------------------

### Run and Inspect Queries in Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Executes named queries against the graph and inspects the results. This step is crucial for verifying data correctness and ensuring the graph meets domain expectations. It requires providing parameters for the entry point entity.

```python
# Run a query
cruxible_query(instance_id, "query_name", params={"primary_key_property": "value"})

# Inspect traversal trace
cruxible_receipt(receipt_id)
```

--------------------------------

### Ingest Source Data into Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Loads entity and relationship data into the Cruxible instance. Mappings defined in the configuration file are used for ingestion. It's recommended to ingest entities before relationships and check for errors after each step.

```python
1. cruxible_ingest(instance_id, "<entity_mapping>", file_path="data/<entities>.csv")
2. cruxible_ingest(instance_id, "<another_entity_mapping>", file_path="data/<other_entities>.csv")
3. cruxible_ingest(instance_id, "<relationship_mapping>", file_path="data/<relationships>.csv")
```

--------------------------------

### Iterative Graph Refinement with Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

This workflow describes the process of iteratively refining a graph by evaluating current findings, discovering missing edges, and persisting confirmed candidates. The process is repeated to ensure continuous improvement.

```python
from cruxible import cruxible_evaluate, cruxible_find_candidates, cruxible_add_relationship

# Initial evaluation
current_findings = cruxible_evaluate()
print(f"Initial findings: {current_findings}")

# Discover potential missing edges
new_candidates = cruxible_find_candidates()
print(f"Found {len(new_candidates)} candidates.")

# Add confirmed candidates to the graph
for candidate in new_candidates:
    cruxible_add_relationship(candidate)

# Re-evaluate after adding new relationships
updated_findings = cruxible_evaluate()
print(f"Updated findings: {updated_findings}")

# Compare counts to track refinement progress
print(f"Graph refined. Initial findings: {len(current_findings)}, Updated findings: {len(updated_findings)}")
```

--------------------------------

### Cruxible Configuration: Entity Type Properties

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Defines how to configure properties for entity types in Cruxible. Key aspects include marking primary keys, handling optional fields, defining enumerations, and setting up indexes for frequent filtering.

```yaml
entity_types:
  - name: User
    properties:
      - name: user_id
        type: integer
        primary_key: true
      - name: username
        type: string
        required: true # Default is true, explicitly shown here
      - name: email
        type: string
        optional: true # Allows null values
      - name: status
        type: string
        enum: ["active", "inactive", "pending"] # Restricts values
      - name: last_login
        type: datetime
        indexed: true # For frequent filtering on login times
```

--------------------------------

### Review Cruxible Edges Workflow

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

A workflow for reviewing and acting upon specific edges within the graph. It starts with querying to obtain a receipt ID, followed by using `cruxible_feedback` to manage edge status.

```python
1. cruxible_query(instance_id, "query_name", params={...}) # Get a receipt_id
2. cruxible_feedback(instance_id, receipt_id, edge_id, "flag", source="human")
3. Re-run the query to confirm behavior changes
```

--------------------------------

### Explain Receipt with CLI

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Provides a command-line interface to explain a receipt. Supports outputting the traversal explanation in markdown format or as a Mermaid diagram.

```bash
cruxible explain --receipt RCP-17b864830ada --format markdown
# Detailed traversal explanation in markdown format

cruxible explain --receipt RCP-17b864830ada --format mermaid
# Mermaid diagram of the traversal DAG
```

--------------------------------

### GET /cruxible_list

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/mcp-tools.md

Lists entities, edges, receipts, feedback, or outcomes with optional filtering capabilities.

```APIDOC
## GET /cruxible_list

### Description
Lists various resources within the Cruxible AI Core, such as entities, edges, receipts, feedback, or outcomes. Supports filtering by various criteria to refine the results.

### Method
GET

### Endpoint
/cruxible_list

### Parameters
#### Query Parameters
- **instance_id** (string) - Required - Instance ID
- **resource_type** (string) - Required - Allowed values: "entities", "edges", "receipts", "feedback", or "outcomes"
- **entity_type** (string) - Conditional - Required when `resource_type="entities"`
- **relationship_type** (string) - Optional - Filter edges by relationship type (only for `resource_type="edges"`)
- **query_name** (string) - Optional - Filter receipts by query name
- **receipt_id** (string) - Optional - Filter feedback/outcomes by receipt
- **limit** (int) - Optional - Maximum items (default: 50)
- **property_filter** (dict) - Optional - Exact property matches, AND semantics (entities and edges only)

### Request Example
```json
{
  "instance_id": "your_instance_id",
  "resource_type": "edges",
  "relationship_type": "WORKS_FOR",
  "limit": 10
}
```

### Response
#### Success Response (200)
- **items** (list[dict]) - Resource items
- **total** (int) - Total count

#### Response Example
```json
{
  "items": [
    {
      "from_type": "Person",
      "from_id": "person_123",
      "to_type": "Company",
      "to_id": "company_456",
      "relationship_type": "WORKS_FOR",
      "edge_key": 1,
      "properties": {
        "start_date": "2022-01-01"
      }
    }
  ],
  "total": 150
}
```

**Edge items** (when `resource_type="edges"`):
- **from_type** (string) - Source entity type
- **from_id** (string) - Source entity ID
- **to_type** (string) - Target entity type
- **to_id** (string) - Target entity ID
- **relationship_type** (string) - Relationship type
- **edge_key** (int) - Edge key for use with `cruxible_feedback`
- **properties** (dict) - Edge properties
```

--------------------------------

### Cruxible Get Entity

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Retrieves a specific entity from the graph by its type and ID. Returns 'Not found.' if the entity does not exist.

```APIDOC
## GET /cruxible/entity

### Description
Look up a specific entity by type and ID.

### Method
GET

### Endpoint
/cruxible/entity

### Parameters
#### Query Parameters
- **type** (string) - Required - Entity type
- **id** (string) - Required - Entity ID

### Request Example
```bash
cruxible get-entity --type Drug --id warfarin
```

### Response
#### Success Response (200)
- **entity_properties** (object) - A JSON object containing the properties of the found entity.

#### Error Response (404)
- **message** (string) - "Not found."

#### Response Example
```json
{
  "entity_properties": {
    "drug_id": "warfarin",
    "name": "Warfarin",
    "therapeutic_class": "anticoagulant"
  }
}
```
```

--------------------------------

### Execute MITRE ATT&CK Queries via CLI

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/demos/mitre-attack/README.md

Demonstrates how to execute pre-defined MITRE ATT&CK queries using the Cruxible CLI. These commands allow users to retrieve specific information about threat groups, techniques, mitigations, and software by specifying query names and parameters.

```bash
cruxible query --query group_techniques --param group_id=G0007
cruxible query --query technique_mitigations --param technique_id=T1055
cruxible query --query technique_detections --param technique_id=T1055
cruxible query --query group_software --param group_id=G0032
```

--------------------------------

### Show Cruxible CLI Help and Version

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Displays general help information for the Cruxible CLI or its specific version. These commands do not require any arguments.

```bash
cruxible --help
cruxible --version
```

--------------------------------

### GET /cruxible_schema

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/mcp-tools.md

Returns the active configuration schema for a given instance, including entity types, relationships, queries, and constraints.

```APIDOC
## GET /cruxible_schema

### Description
Retrieves the active configuration schema for a specified instance. This schema defines the structure of the data, including entity types, relationship types, defined queries, and constraints.

### Method
GET

### Endpoint
/cruxible_schema

### Parameters
#### Query Parameters
- **instance_id** (string) - Required - Instance ID

### Request Example
```json
{
  "instance_id": "your_instance_id"
}
```

### Response
#### Success Response (200)
- **schema** (dict) - Full config schema dict including entity types, relationships, queries, and constraints.

#### Response Example
```json
{
  "schema": {
    "entity_types": {
      "Person": {
        "properties": {
          "name": {"type": "string"}
        }
      }
    },
    "relationship_types": {
      "WORKS_FOR": {
        "from_type": "Person",
        "to_type": "Company"
      }
    },
    "queries": {},
    "constraints": {}
  }
}
```
```

--------------------------------

### List Resources via CLI

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Provides command-line equivalents for listing different types of resources. These commands allow users to specify the resource type (entities, edges, feedback, receipts) and apply filters such as entity type, relationship type, property filters, or query names. This offers a flexible way to access graph information.

```bash
cruxible list entities --type Drug --limit 50
cruxible list edges --relationship interacts_with --limit 20
cruxible list feedback --receipt RCP-17b864830ada
cruxible list receipts --query-name check_interactions

```

--------------------------------

### Sample Entities

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Shows a sample of entities of a given type for quick inspection.

```APIDOC
## Sample Entities

### Description
Shows a sample of entities of a given type for quick inspection.

### Method
GET

### Endpoint
/cruxible/sample

### Parameters
#### Query Parameters
- **type** (string) - Required - Entity type to sample
- **limit** (integer) - Optional - Number of entities to show (default: 5)

### Request Example
```bash
GET /cruxible/sample?type=Drug&limit=3
```

### Response
#### Success Response (200)
- **entities** (array) - A list of sample entities.

#### Response Example
```json
{
  "entities": [
    {
      "id": "drug_1",
      "type": "Drug",
      "name": "Warfarin"
    },
    {
      "id": "drug_2",
      "type": "Drug",
      "name": "Aspirin"
    }
  ]
}
```
```

--------------------------------

### Add Entity via CLI

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Provides a command-line interface to add or update a single entity in the graph. This example shows how to add a new 'Drug' entity with its properties specified as a JSON string.

```bash
cruxible add-entity --type Drug --id metoprolol \
  --props '{"drug_id": "metoprolol", "name": "Metoprolol", "therapeutic_class": "beta_blockers"}'
# Entity Drug:metoprolol added.
```

--------------------------------

### Initialize Cruxible Instance

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Initializes a new Cruxible instance in the current directory, creating a `.cruxible/` directory. Requires a configuration file path and optionally accepts a data directory path.

```bash
cruxible init --config <path> [--data-dir <dir>]
# Example:
cruxible init --config config.yaml --data-dir ./data
# Initialized .cruxible/ in /path/to/project
```

--------------------------------

### Execute Named Queries via CLI

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/demos/sanctions-screening/README.md

Demonstrates how to execute pre-defined named queries using the Cruxible CLI. These queries are used for sanctions screening, identifying offshore connections, and retrieving full risk profiles. Requires specifying the query name and relevant parameters like node or entity IDs.

```bash
cruxible query --query screen_company --param node_id=<offshore_company_node_id>
cruxible query --query find_offshore --param entity_id=<sanctioned_entity_id>
cruxible query --query full_risk_profile --param entity_id=<sanctioned_entity_id>
```

--------------------------------

### Cruxible Get Relationship

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Retrieves a specific relationship between two entities by their types, IDs, and the relationship type. An optional edge key can be provided for disambiguation if multiple relationships of the same type exist between the entities.

```APIDOC
## GET /cruxible/relationship

### Description
Look up a specific relationship by its endpoints and type.

### Method
GET

### Endpoint
/cruxible/relationship

### Parameters
#### Query Parameters
- **from_type** (string) - Required - Source entity type
- **from_id** (string) - Required - Source entity ID
- **relationship** (string) - Required - Relationship type
- **to_type** (string) - Required - Target entity type
- **to_id** (string) - Required - Target entity ID
- **edge_key** (integer) - Optional - Edge key for multi-edge disambiguation

### Request Example
```bash
cruxible get-relationship --from-type Drug --from-id warfarin --relationship interacts_with --to-type Drug --to-id simvastatin
```

### Response
#### Success Response (200)
- **relationship_properties** (object) - A JSON object containing the properties of the found relationship.

#### Error Response (404)
- **message** (string) - "Not found."

#### Error Response (409)
- **message** (string) - "Multiple edges exist. Specify --edge-key."

#### Response Example
```json
{
  "relationship_properties": {
    "source": "drugbank",
    "confidence_score": 0.95
  }
}
```
```

--------------------------------

### Sample Cruxible Entities

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Shows a sample of entities of a specified type for quick inspection. Users can define the entity type and the maximum number of entities to display.

```bash
cruxible sample --type <entity_type> [--limit <n>]
```

```bash
cruxible sample --type Drug --limit 3
```

--------------------------------

### Python Workflow for Cruxible Graph Operations

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Demonstrates a complete end-to-end workflow using the Cruxible Python API. It covers validating configuration, initializing an instance, ingesting data, evaluating graph quality, running queries, providing feedback on results, recording outcomes, discovering missing relationships, and adding confirmed relationships.

```python
# 1. Validate config
cruxible_validate(config_path="config.yaml")

# 2. Initialize instance
init_result = cruxible_init(root_dir=".", config_path="config.yaml")
instance_id = init_result["instance_id"]

# 3. Ingest data (entities first, then relationships)
cruxible_ingest(instance_id, "drugs", file_path="data/drugs.csv")
cruxible_ingest(instance_id, "enzymes", file_path="data/enzymes.csv")
cruxible_ingest(instance_id, "interactions", file_path="data/interactions.csv")

# 4. Evaluate graph quality
eval_result = cruxible_evaluate(instance_id)
print(f"Graph has {eval_result['entity_count']} entities, {eval_result['edge_count']} edges")

# 5. Run queries with receipt
query_result = cruxible_query(
    instance_id,
    query_name="check_interactions",
    params={"drug_id": "warfarin"}
)
receipt_id = query_result["receipt_id"]

# 6. Provide feedback on results
cruxible_feedback(
    instance_id,
    receipt_id=receipt_id,
    action="approve",
    source="human",
    from_type="Drug",
    from_id="warfarin",
    relationship="interacts_with",
    to_type="Drug",
    to_id="simvastatin"
)

# 7. Record outcome
cruxible_outcome(
    instance_id,
    receipt_id=receipt_id,
    outcome="correct",
    detail={"reviewed_by": "clinical_pharmacist"}
)

# 8. Discover missing relationships
candidates = cruxible_find_candidates(
    instance_id,
    relationship_type="interacts_with",
    strategy="shared_neighbors",
    via_relationship="metabolized_by"
)

# 9. Add confirmed candidates
cruxible_add_relationship(
    instance_id,
    relationships=[{
        "from_type": "Drug",
        "from_id": candidates["candidates"][0]["from_id"],
        "relationship": "interacts_with",
        "to_type": "Drug",
        "to_id": candidates["candidates"][0]["to_id"],
        "properties": {"source": "shared_neighbors", "confidence": 0.8}
    }]
)

```

--------------------------------

### Validate Graph Quality with Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Assesses the structural integrity and quality of the graph. This includes checking for orphans, violations, and coverage gaps using `cruxible_evaluate` and performing deeper analysis with prompts like `review_graph`.

```python
# Structural health check
cruxible_evaluate(instance_id)

# Deeper analysis and discovery
cruxible_prompt("review_graph", {"instance_id": "<instance_id>"})
```

--------------------------------

### Initialize or Reload Cruxible Instance

Source: https://context7.com/cruxible-ai/cruxible-core/llms.txt

Creates a new Cruxible Core instance or reloads an existing one. It requires a root directory and configuration path for new instances, and returns an instance ID for subsequent operations. Reloading an existing instance only requires the root directory.

```python
# Create new instance
result = cruxible_init(
    root_dir="./my-project",
    config_path="config.yaml",
    data_dir="./data"
)
# Returns: {"instance_id": "inst_abc123", "status": "initialized"}

# Reload existing instance (omit config_path)
result = cruxible_init(root_dir="./my-project")
# Returns: {"instance_id": "inst_abc123", "status": "loaded"}
```

```bash
cruxible init --config config.yaml --data-dir ./data
# Initialized .cruxible/ in /path/to/project
```

--------------------------------

### Schema

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Displays the configuration schema for the current Cruxible instance.

```APIDOC
## Schema

### Description
Displays the configuration schema for the current Cruxible instance.

### Method
GET

### Endpoint
/cruxible/schema

### Parameters
No parameters. Reads the `.cruxible/` instance in the current directory.

### Response
#### Success Response (200)
- **schema** (object) - The configuration schema.

#### Response Example
```json
{
  "schema": {
    "entity_types": { ... },
    "relationship_types": { ... }
  }
}
```
```

--------------------------------

### Discover Cross-References with Cruxible

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Facilitates the discovery of relationships between entities, especially for data not originating from CSV files. It involves adding entities, finding candidate relationships using various strategies, and persisting confirmed matches.

```python
# For entities from free text or external sources:
cruxible_add_entity(instance_id, "entity_type", { ...entity_properties... })

# For cross-dataset relationship types:
cruxible_sample(instance_id, "entity_type_1")
cruxible_sample(instance_id, "entity_type_2")
cruxible_find_candidates(instance_id, "entity_type_1", "entity_type_2", strategy="property_match", property="name", match_type="iequals")
cruxible_find_candidates(instance_id, "entity_type_1", "entity_type_2", strategy="shared_neighbors", intermediary_type="some_type")
cruxible_add_relationship(instance_id, "relationship_type", "entity_id_1", "entity_id_2", source="ai_review", confidence=0.9, evidence="matched on name")
```

--------------------------------

### Feedback-to-Constraint Workflow (Conceptual)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/CLAUDE.md

This snippet describes a conceptual workflow for converting feedback patterns into actionable constraints within Cruxible Core. It involves analyzing feedback, adding new constraints via an MCP tool, and then evaluating the system against these new constraints.

```text
# Feedback-to-Constraint Workflow
# 1. Use analyze_feedback MCP prompt or manually review feedback
# 2. Call cruxible_add_constraint to encode the pattern as a rule
# 3. Run cruxible_evaluate to verify constraints flag expected violations

# Config write-back uses atomic temp-file + rename via config/loader.py:save_config()
```

--------------------------------

### Cruxible Configuration: Relationship Definition

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/for-ai-agents.md

Details the configuration for defining relationships between entity types in Cruxible. It specifies the source and target entity types, and recommends including properties like source, confidence, and evidence for AI-inferred relationships.

```yaml
relationships:
  - name: FOLLOWS
    from: User
    to: User
    description: "Indicates one user follows another."
    properties:
      - name: timestamp
        type: datetime
      - name: source
        type: string # e.g., 'manual', 'inferred_llm'
      - name: confidence
        type: float # Score from inference
      - name: evidence
        type: string # Details about the inference process
    inverse: "FOLLOWED_BY" # Defines the inverse relationship
```

--------------------------------

### Get Entity by Type and ID (Bash)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Retrieves a specific entity from the graph using its type and ID. It prints entity properties if found, or 'Not found.' if the entity does not exist. This command requires the entity type and ID as arguments.

```bash
cruxible get-entity --type <entity_type> --id <entity_id>
```

--------------------------------

### Configure MCP Server for Cruxible (Codex)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/README.md

This TOML configuration snippet sets up the Cruxible MCP server for the Codex AI agent. It defines the command and environment variables required to run the server.

```toml
[mcp_servers.cruxible]
command = "cruxible-mcp"

[mcp_servers.cruxible.env]
CRUXIBLE_MODE = "admin"
```

--------------------------------

### Prompt Management API

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Manages workflow prompts, allowing listing available prompts and reading specific prompts with arguments.

```APIDOC
## Prompt Management API

### Description
Manages workflow prompts, allowing listing available prompts and reading specific prompts with arguments.

### List Prompts

#### Method
GET

#### Endpoint
/cruxible/prompt/list

#### Parameters
No options. Lists all available prompts with their descriptions and required arguments.

#### Response
##### Success Response (200)
- **prompts** (array) - A list of available prompts.

##### Response Example
```json
{
  "prompts": [
    {
      "name": "onboard_domain",
      "description": "Onboard a new domain.",
      "required_args": ["domain"]
    },
    {
      "name": "common_workflows",
      "description": "Common tool sequences for debugging, review, refinement.",
      "required_args": []
    }
  ]
}
```

### Read Prompt

#### Method
GET

#### Endpoint
/cruxible/prompt/read

#### Parameters
##### Query Parameters
- **name** (string) - Required - Prompt name (from `prompt list`)
- **arg** (string) - Optional - Prompt argument as `KEY=VALUE` (repeatable)

#### Request Example
```bash
GET /cruxible/prompt/read?name=onboard_domain&arg=domain=drug_interactions
```

#### Response
##### Success Response (200)
- **prompt_content** (string) - The content of the requested prompt.

##### Response Example
```json
{
  "prompt_content": "# Onboarding Workflow for Drug Interactions\n1. Load drug data...\n2. Define relationships..."
}
```
```

--------------------------------

### Get Relationship by Endpoints and Type (Bash)

Source: https://github.com/cruxible-ai/cruxible-core/blob/main/docs/cli-reference.md

Retrieves a specific relationship between two entities based on their types, IDs, and the relationship type. An optional edge key can be provided for disambiguation. The command returns relationship properties if found, or 'Not found.' if the relationship does not exist. It errors if multiple edges exist and no edge key is specified.

```bash
cruxible get-relationship --from-type <type> --from-id <id> \
  --relationship <rel> --to-type <type> --to-id <id> [--edge-key <int>]
```