Build Digital Partners

# Helm OS: The Compute Sidecar Pattern
# The main orchestration loop never blocks. Heavy lifting is physically isolated.

from app.core.runtime import managed_workflow

@managed_workflow
async def autonomous_agent(context: WorkflowContext, file_bytes: bytes):
    
    # 1. COMPUTE SIDECAR: Decouple System 1 (UI) from System 2 (Heavy Reasoning)
    # Offloads intensive workloads to prevent event loop blocking and fatal crashes.
    result = await context.compute.run_cpu_task(
        heavy_data_parser, 
        file_bytes, 
        resources={"cpu": 1.0}
    )
    context.workflow_data.update(result)

    # 2. BIFURCATED PERSISTENCE (BPE): Ultra-fast O(1) state saves (<20ms)
    # Bypasses massive JSON serialization to eliminate latency and RCE vulnerabilities.
    await context.save_checkpoint_delta()

# Helm OS: Micro-Step Idempotency
@managed_step(step_id="step_fetch_heavy_data")
async def _fetch_data(context: WorkflowContext, query: str) -> dict:
    # If the Ray cluster crashes during a massive multi-week mission,
    # this expensive I/O call will NEVER be executed twice.
    return {"data": f"Results for {query}"}

# Imports the authoritative state container that holds workflow_data and system services
from app.state.adapters import WorkflowContext
# Imports the kernel runtime decorator that registers the function with the orchestration engine
from app.core.runtime import managed_workflow

@managed_workflow 
async def domain_specific_business_workflow(context: WorkflowContext, args: dict):
    # 1. Domain developers use live, interactive system channels seamlessly
    await context.notifications.send(["Initiating enterprise workflow..."])
    
    # 2. Update standard database-bound state variables
    context.workflow_data["current_milestone"] = "verification"
    
    # 3. Save progress. The developer is completely isolated from the mechanics
    # of state serialization, network filtering, or asset stripping.
    await context.save()

# ---------------------------------------------------------
# STEP 1: The Ontology (domain_schema.yaml)
# Define your entities and how they relate. Helm OS compiles 
# this into strict Python models and Neo4j edge mappings.
# ---------------------------------------------------------
slots:
  meta_client_id:
    slot_uri: ergatis:retainedBy  # Helm OS automatically translates this to a Graph Edge!
    domain: Jobs
    range: Clients

classes:
  Jobs:
    is_a: DomainEntity
    attributes:
      meta_job_title:
        range: string
        required: true
      meta_client_id:
        range: Clients

...

# ---------------------------------------------------------
# STEP 2: The Workflow (helpers_system_1.py)
# Update memory natively in Python. No Cypher queries, 
# no API calls, no embedding scripts.
# ---------------------------------------------------------
async def create_new_job(context: WorkflowContext, job_id: str, client_id: str):
    
    # 1. Define your standard Python dictionary
    job_data = {
        "id": job_id,
        "canonical_uri": "ergatis:Jobs",
        "meta_job_title": "Senior Cloud Architect",
        "meta_client_id": client_id  # The OS intercepts this Foreign Key
    }

    # 2. Package as a Semantic Entity
    semantic_entity = {
        "type": "SEMANTIC_ENTITY",
        "entity": job_data
    }

    # 3. Commit to the O(1) Shadow Buffer
    await context.memorize(semantic_entity)

    # MAGIC: Once the buffer saturates, the 'Archivist' Sidecar takes over asynchronously.
    # It generates a 768-D Vector Embedding for the job, strips 'meta_client_id', 
    # and projects a strict (Jobs)-[:retainedBy]->(Clients) edge into Neo4j!

# ---------------------------------------------------------
# STEP 1: Zero-Boilerplate Intent Mapping (domain_manifest.yaml)
# Map frontend UI clicks to Cognitive Primitives. No routing scripts required.
# ---------------------------------------------------------
manifest:
  signal_mappings:
    - raw_uri_pattern: "JOBS.SELECT"
      cognitive_primitive: "FOCUS_SHIFT"  # Helm OS automatically tracks what the user is looking at
      target_entity_type: "Job"
      meta:
        description: "User is viewing a specific job requisition" # JIT injected into LLM context

# ---------------------------------------------------------
# STEP 2: Silent Background Execution (workflows.py)
# Background workers execute logic without colliding in the main chat UI.
# ---------------------------------------------------------
@global_registry.register_bg("analyze_candidates")
@managed_workflow
async def analyze_candidates_bg(context: WorkflowContext, args: dict):
    # Perform heavy processing...
    
    # Update the UI directly, but keep chat_state="off" to protect the AMA Agent's "Single Voice"
    await context.notifications.send(
        message_list=["System: Candidate pool optimized."],
        chat_state="off", 
        done=True
    )

# ---------------------------------------------------------
# STEP 3: The Omniscient AMA Agent (workflows.py)
# Zero state-recovery loops. Zero custom prompt injections. 
# ---------------------------------------------------------
@global_registry.register_fg("ama_agent_langgraph", is_default=True)
@managed_workflow
async def ama_agent_runner(context: WorkflowContext, args: dict):
    while True:
        # 1. Wait for user input (Helm OS auto-suspends and recovers state if needed)
        user_input = await context.notifications.wait_for_input()
        
        # 2. Call the LLM. 
        # MAGIC: The InferenceGateway autonomously weaves the "FOCUS_SHIFT" from Step 1 
        # and the background states from Step 2 into the LLM's context window Just-In-Time.
        success, response = await context.inference.invoke_chat(
            context=context,
            messages=[HumanMessage(content=user_input)]
        )
        
        # 3. Respond with the Single Voice
        await context.notifications.send(
            message_list=[response.content],
            chat_state="on"
        )

# ---------------------------------------------------------
# CAPABILITY 1: O(1) Exact Match Filtering
# The AMA agent uses this to instantly retrieve known entities without vector math.
# ---------------------------------------------------------
@tool
async def exact_match_entity_filter(entity_class_name: str, filter_key: str, filter_value: str, config: RunnableConfig):
    # Executes a deterministic, O(1) database lookup for precise facts
    results = await context.inference.retrieve_by_exact_match(
        context=context,
        entity_class_name=entity_class_name,
        filter_key=filter_key,
        filter_value=filter_value
    )
    return json.dumps(results)

# ---------------------------------------------------------
# CAPABILITY 2: Structural Graph Traversal 
# The AMA agent uses this to "walk" graph edges and discover hidden relationships.
# ---------------------------------------------------------
@tool
async def traverse_graph_relationships(source_id: str, relationship_type: str, config: RunnableConfig):
    # Bypasses vector similarity to execute a strict, multi-hop Cypher traversal 
    # (e.g., Finding all 'Candidates' connected to a specific 'Job' via the 'ranksCandidate' edge)
    cypher_query = f"""
    MATCH (src)-[r:{relationship_type}]-(target)
    WHERE src.id = $source_id
    RETURN properties(target)
    """
    results = await context.inference.execute_cypher(
        context=context,
        query=cypher_query,
        params={"source_id": source_id}
    )
    return json.dumps(results)

# ---------------------------------------------------------
# CAPABILITY 3: Hybrid Semantic Vector Search
# The AMA agent uses this for fuzzy, natural language discovery.
# ---------------------------------------------------------
@tool
async def search_specific_domain_entity(entity_class_name: str, query: str, config: RunnableConfig):
    # Generates a 768-D embedding and executes a semantic similarity search 
    # across the Knowledge Graph, utilizing metadata filters to prevent dilution.
    results = await context.inference.retrieve(
        context=context,
        query=query,
        mode="HYBRID", # Combines Vector facts and Community insights
        limit=20
    )
    return json.dumps(results)