clelandlab-HAL 0.0.0__tar.gz

clelandlab_hal-0.0.0/HAL/HAL_answer.py

@@ -0,0 +1,18 @@
+from google.genai import types
+from . import memory
+from .HAL_gather_document import gather_document
+from .utils import add_generative_cost, docs2text, sequence2text
+from .display import log
+
+def answer(prompt, sequence):
+    docs = gather_document(prompt)
+    system_instruction = f"You are a researcher on experimental quantum computing. Answer the question concisely with NO comments. Use the provided context and the following documents (you might refer to document title, but NOT document number):\n\n{docs2text(docs)}"
+    model = memory.session.get("model", "gemini-flash-latest")
+    log(f"[HAL] Answering ({model})...", "Answering")
+    res = memory.client.models.generate_content(
+        model=model,
+        config=types.GenerateContentConfig(system_instruction=system_instruction),
+        contents=f"Context:\n\n{sequence2text(sequence)}\n\nQuestion:\n\n{prompt}"
+    )
+    add_generative_cost(res)
+    return res.text

clelandlab_hal-0.0.0/HAL/HAL_code.py

@@ -0,0 +1,61 @@
+from google.genai import types
+import json
+from . import memory
+from .HAL_gather_document import gather_document
+from .utils import add_generative_cost, docs2text, state_type2text, get_exec_import
+from .display import log
+
+system_instruction = lambda docs, import_variable, STATE: f"""You are a world class programming AI that generates Python code based on requirements. Write clear and concise code using the given documents.
+
+# Coding Guidelines
+
+The code should be runnable. Absolutely NO comments, NO explanations, NO side behaviors like printing messages. Do NOT use try-except to wrap all the code, it is taken care of by the caller. If any user input is really necessary (e.g. missing data directory), specify them in `request_input`, which should be a code snippet that assigns values to variables in `STATE`. It will be modified by the user to input the necessary values.
+
+
+In addition to all the imported packages below, you have two global variables: `STATE` and `INVOKE`:
+1. `STATE` is a dictionary that persists across steps. Use it to store any variables or data that need to be retained or exported. Note that you cannot assign to `STATE`, you can only modify its contents.
+  - `STATE["SIGNAL"]` is a special variable for signal. SIGNAL should be a short string in natural language, describing the key outcome of the code execution. If there is no signal description in prompt, set it to "SUCCESS" or a descriptive error message.
+2. `INVOKE` is a function that can be used to directly run other code segments or steps. `INVOKE("Code Segment [ID]")` can invoke a code segment in documents. When possible, you should use `INVOKE` instead of repeating code segments in documents.
+  - Sometimes you may be instructed to invoke a number, e.g., `INVOKE(3)`, when the manager decides to run a previous step. Faithfully follow the instruction to invoke the specified step.
+
+## Existing Variables in STATE
+
+Take the following variables as given. Do NOT check or request user input! Not every variable is relevant to your task. Only use the specified or relevant variables.
+
+{state_type2text(STATE)}
+
+## Documents
+
+{docs2text(docs)}
+
+## Imports
+
+The following packages are already imported and ready to use. Do NOT import these packages again!
+
+```python
+{get_exec_import(import_variable)}
+```"""
+
+def code(prompt, import_variable={ "name": "HAL" }, _doc={}):
+    docs = gather_document(prompt)
+    _doc["code"] = list(map(lambda d: d["id"], docs))
+    model = memory.session.get("model", "gemini-flash-latest")
+    log(f"[HAL] Coding ({model})...", "Coding")
+    res = memory.client.models.generate_content(
+        model=model,
+        config=types.GenerateContentConfig(
+            response_mime_type="application/json",
+            response_schema=types.Schema(type=types.Type.OBJECT, required=["code"], properties={
+                "code": types.Schema(type=types.Type.STRING),
+                "request_input": types.Schema(type=types.Type.STRING, description="some lines of code assigning values to variables in STATE. ONLY assignment statements are allowed. This will be modified by the user.")
+            }),
+            system_instruction=system_instruction(docs, import_variable, memory.session["STATE"])
+        ),
+        contents=prompt
+    )
+    add_generative_cost(res)
+    r = json.loads(res.text)
+    request_input = r.get("request_input")
+    if request_input == "":
+        request_input = None
+    return r["code"], request_input

clelandlab_hal-0.0.0/HAL/HAL_gather_document.py

@@ -0,0 +1,66 @@
+from google.genai import types
+from . import memory
+import json
+from .utils import docs2text, add_generative_cost
+from .display import log
+
+system_instruction = f"""You are a researcher preparing documents for a coming task. Your goal is to gather all relevant documents from the database. You will be shown the main task, a list of queries already searched, and the documents gathered so far.
+
+Your task is to:
+1. **Filter:** Review all gathered documents. Identify the documents that are completely irrelevant or useless for the task. List their *indices* in the "remove" key.
+2. **Stop:** If gathered documents are sufficient or relevant queries are already searched, provide an empty list for "query". You must provide search queries if all documents are removed in the previous step.
+3. **Search:** Review the task and the *relevant* documents. Provide new search queries to find missing information or to recursively find documents/tools/methods mentioned in the relevant documents. Unless the task is to make a plan, you MUST search for ALL things refered by current documents. **Do NOT search for methods in common Python packages like "scipy", "numpy", "matplotlib", "yaml", etc.**
+"""
+
+user_content = lambda task, docs, query_section: f"""# Task:
+
+{task}
+
+# Searched Queries (do NOT repeat these):
+
+{query_section}
+
+# Gathered Documents:
+
+{docs2text(docs)}"""
+
+filter_docs = lambda indices_to_remove, doc_id_list: [doc_id for index, doc_id in enumerate(doc_id_list) if index not in set(indices_to_remove)]
+
+def gather_document(query, max_iterations=5):
+    log("[HAL] Gathering documents...", "Gathering Documents")
+    doc_ids = []
+    def search(keyword):
+        res = memory.search(keyword)
+        for doc_id, _ in res:
+            if doc_id not in doc_ids:
+                doc_ids.append(doc_id)
+        return len(res)
+    searched_queries = []
+    search(query)
+    for i in range(max_iterations):
+        docs = map(memory.get, doc_ids)
+        query_section = '\n'.join([f"- {q}" for q in searched_queries])
+        config = types.GenerateContentConfig(
+            thinking_config=types.ThinkingConfig(thinking_level="LOW"),
+            response_mime_type="application/json",
+            response_schema=types.Schema(type=types.Type.OBJECT, required=["remove", "query"], properties={
+                "remove": types.Schema(type=types.Type.ARRAY, items=types.Schema(type=types.Type.INTEGER)),
+                "query": types.Schema(type=types.Type.ARRAY, items=types.Schema(type=types.Type.STRING))}),
+            system_instruction=system_instruction
+        )
+        res = memory.client.models.generate_content(
+            model="gemini-flash-latest",
+            contents=user_content(query, docs, query_section),
+            config=config)
+        add_generative_cost(res)
+        res_json = json.loads(res.text)
+        doc_ids = filter_docs(res_json.get("remove", []), doc_ids)
+        new_queries = res_json.get("query", [])
+        for q in new_queries:
+            search(q)
+            searched_queries.append(q)
+        log(f"  {i}. search: {new_queries} -> {len(doc_ids)}", "Gathering Documents")
+        if len(new_queries) == 0:
+            break
+    log(f"  > doc count: {len(doc_ids)}")
+    return [memory.get(doc_id) for doc_id in doc_ids]

clelandlab_hal-0.0.0/HAL/HAL_plan.py

@@ -0,0 +1,43 @@
+from google.genai import types
+import json
+from . import memory
+from .HAL_gather_document import gather_document
+from .utils import add_generative_cost, docs2text, sequence2text, state_type2text
+from .display import log
+
+system_instruction = lambda docs: f"""You are a research manager leading a team. Given the step history, make a concise plan for the next step.
+
+Your team members can access all the documents, but NOT the step history. Make sure to provide sufficient details in the prompt to make your team members work without the step history, like the detailed information from user input.
+
+Do NOT repeat document content in the prompt. Specify relevant documents title or keyword so that your team members can search for them. It's not recommended to refer to plan documents unless necessary. Do NOT use document indices, they are not accessible to your team members.
+
+SIGNAL is a special string variable that describes the key outcome of the step. It can include some critical numbers like goodness of fitting, or short messages like "SUCCESS" or error. Provide a SIGNAL description in your prompt, so that your team can present the result to you. 
+
+If you want to repeat a step, execute a step for multiple times, or execute a code segment, ask your team to INVOKE it by its step index or the code segment name in the prompt.
+
+If the task requested by the user is completed, set the step type to "end" and output empty prompt.
+
+You may literally use an existing plan, with modification or added information. Refer to the following documents to make the plan:
+
+{docs2text(docs)}"""
+
+def plan(sequence, _doc={}):
+    docs = gather_document(f'**Make a plan for the next step. ONLY find a few relevant high-level plan documents. All implementation details are irrelevant.**\n\nStep history:\n\n{sequence2text(sequence)}')
+    _doc["plan"] = list(map(lambda d: d["id"], docs))
+    model = memory.session.get("model", "gemini-flash-latest")
+    log(f"[HAL] Planning ({model})...", "Planning")
+    config = types.GenerateContentConfig(
+        system_instruction=system_instruction(docs),
+        response_mime_type="application/json",
+        response_schema=types.Schema(type=types.Type.OBJECT, required=["type", "prompt"], properties={
+            "type": types.Schema(type=types.Type.STRING, description="Type of the next step, one of: 'code', 'end'."),
+            "prompt": types.Schema(type=types.Type.STRING, description="Prompt for your team to complete the step, as a prompt for a large language model.")
+        })
+    )
+    res = memory.client.models.generate_content(
+        model=model,
+        config=config,
+        contents=f"# Step history:\n\n{sequence2text(sequence)}\n\n # Current STATE variables:\n\n{state_type2text(memory.session['STATE'])}"
+    )
+    add_generative_cost(res)
+    return json.loads(res.text)

clelandlab_hal-0.0.0/HAL/HAL_sort.py

@@ -0,0 +1,28 @@
+from google.genai import types
+import json
+from . import memory
+from .utils import add_generative_cost
+from .display import log
+
+system_instruction = '''You are an expert at classifying user prompts into categories. Given a user prompt, classify it into one of the following categories:
+
+- "query": if the prompt is asking for an answer, explanation, or natural language response, like **how to** write a function, why something is wrong, or to write a document.
+- "action": if the prompt is requesting to perform a task or action, like take a measurement or run a data analysis or fix something.
+'''
+
+def sort(prompt):
+    log("[HAL] Sorting...", "Sorting")
+    config = types.GenerateContentConfig(
+        thinking_config=types.ThinkingConfig(thinking_level="LOW"),
+        system_instruction=system_instruction,
+        response_mime_type="application/json",
+        response_schema=types.Schema(type=types.Type.OBJECT, required=["category"], properties={ "category": types.Schema(type=types.Type.STRING) })
+    )
+    res = memory.client.models.generate_content(
+        model="gemini-flash-latest",
+        config=config,
+        contents=prompt
+    )
+    category = json.loads(res.text)["category"]
+    log(f"  > {category}")
+    return category

clelandlab_hal-0.0.0/HAL/VERSION

@@ -0,0 +1 @@
+0.0.0

clelandlab_hal-0.0.0/HAL/__init__.py

@@ -0,0 +1,175 @@
+import sys, os, json, random, string, time
+from google import genai
+import ipywidgets as widgets
+from IPython.display import display as _display
+from . import memory, utils, display, run
+from .HAL_gather_document import gather_document
+from .HAL_sort import sort
+from .HAL_plan import plan
+from .HAL_answer import answer
+from .HAL_code import code
+
+handlers = {}
+
+def HAL(query=None):
+    if query is not None and "open the pod bay doors" in query.casefold():
+        return display.show("I'm sorry, Dave. I'm afraid I can't do that.")
+    while True:
+        sequence = memory.session["sequence"]
+        HAL.auto -= 1
+        if "SIGNAL" in memory.session["STATE"]:
+            sequence[-1]["SIGNAL"] = memory.session["STATE"]["SIGNAL"]
+            del memory.session["STATE"]["SIGNAL"]
+        original_cost = memory.session.get("cost", 0)
+        log_cost = lambda: display.log(f"[HAL] Cost: ${memory.session.get('cost', 0)-original_cost:.5f}. (Session Total: ${memory.session.get('cost', 0):.5f})\n")
+        start_time = time.time()
+        if query is not None:
+            category = sort(query)
+            if category == "query":
+                res = answer(query, sequence)
+                log_cost()
+                return display.show(res)
+            sequence.append({ "user input": query, "_type": "user input" })
+        if len(sequence) == 0:
+            return display.show("HAL is ready.")
+        if sequence[-1].get("_type", "") == "end":
+            return display.show("HAL session has ended. Please reset the session using `HAL.reset()`.")
+        display.sequence(sequence)
+        step = { "_doc": {} }
+        res = plan(sequence, _doc=step["_doc"])
+        step["_type"], step["prompt"] = res["type"], res["prompt"]
+        display.log(f"  > {step['_type']}")
+        sequence.append(step)
+        display.sequence(sequence)
+        pause = handlers[step["_type"]](step)
+        display.log(f"[HAL] Step time: {time.time()-start_time:.2f} s")
+        log_cost()
+        display.sequence(sequence)
+        query = None
+        if pause:
+            return display.show("HAL sequence is paused.")
+        if HAL.auto <= 0 or step["_type"] == "end":
+            HAL.auto = 0
+            return display.show("HAL auto is stopped.")
+
+sys.modules[__name__] = HAL
+
+HAL.auto = 0
+HAL.session = memory.session
+
+HAL.memory = memory
+HAL.display = display
+HAL.utils = utils
+
+HAL.gather_document = gather_document
+HAL.sort = sort
+HAL.plan = plan
+HAL.answer = answer
+HAL.code = code
+
+_invoke = lambda name=None, import_variable={}: run.invoke(name, import_variable={ **memory.session, **import_variable })
+
+def _export_ctx():
+    main_namespace = sys.modules.get('__main__')
+    main_namespace.STATE = memory.session["STATE"]
+    main_namespace.INVOKE = _invoke
+    HAL.session = memory.session
+
+def _init(name="", _config=None):
+    memory.session["name"] = name
+    if _config is None:
+        _config = os.path.join(os.path.dirname(__file__), "../config.json")
+    if isinstance(_config, dict):
+        utils.config.update(_config)
+    if isinstance(_config, str):
+        utils.config.update(json.load(open(_config, "r")))
+    memory.client = genai.Client(api_key=utils.config["GEMINI_API_KEY"])
+    display.init()
+    memory.load()
+    display.log("[HAL] Initialized.")
+    HAL.reset()
+HAL.init = _init
+
+def _reset():
+    memory.session.update({ "cost": 0.0, "sequence": [], "STATE": {} })
+    display.log("[HAL] Session reset.")
+    display.sequence(memory.session["sequence"])
+    _export_ctx()
+HAL.reset = _reset
+
+def _save(path="session.json"):
+    display.log(f"[HAL] Session saved to {path}")
+    return json.dump(memory.session, open(path, "w"), indent=2)
+HAL.save = _save
+
+def _load(path="session.json"):
+    display.log(f"[HAL] Session loaded from {path}")
+    memory.session.update(json.load(open(path, "r")))
+    display.sequence(memory.session.get("sequence", []))
+    _export_ctx()
+HAL.load = _load
+
+def _search(*args, **kwargs):
+    res = memory.search(*args, **kwargs)
+    texts = []
+    for id, score in res:
+        doc = memory.get(id)
+        r = f"### `{doc["id"]}`\n- **score**: {score}\n"
+        for k, v in doc.items():
+            if k in ["id", "content", "embedding"]:
+                continue
+            r += f"- **{k}**: {v}\n"
+        r += f"\n\n{doc['content']}\n\n"
+        texts.append(r)
+    return display.docs(texts)
+HAL.search = _search
+
+def _memorize(content=None, meta={}):
+    if memory.session["name"] == "HAL":
+        return print("[HAL] Error: Please set name to memorize")
+    if "source" not in meta:
+        meta["source"] = memory.session["name"]
+    if isinstance(content, str):
+        return memory.add(content, meta)
+    if content is None:
+        content = len(memory.session.get("sequence", [])) - 1
+    if isinstance(content, int):
+        seq = memory.session.get("sequence", [])
+        if content < 0 or content >= len(seq):
+            return print(f"[HAL] Error: Invalid sequence [{content}]")
+        step = seq[content]
+        if "prompt" not in step or "_code" not in step:
+            return print(f"[HAL] Error: Sequence [{content}] does not contain a valid step to memorize")
+        n = "".join(random.choices(string.ascii_uppercase, k=2)) + str(len(memory.data.keys()))
+        c = f"# Code Segment {n}:\n\n## Prompt:\n\n{step['prompt']}\n\n## Code:\n\nYou can directly run the following code by calling `INVOKE('Code Segment {n}')`\n\n```python\n{step['_code']}\n```"
+        meta["invoke"] = 1
+        return memory.add(c, meta)
+    return print("[HAL] Error: Unsupported content type for memorize")
+HAL.memorize = _memorize
+
+def end_handler(step):
+    step["prompt"] = "Session ended."
+    display.show("[HAL] session ended.")
+    return False
+handlers["end"] = end_handler
+
+def code_handler(step):
+    STATE = memory.session["STATE"]
+    c, request_input = code(step["prompt"], import_variable=memory.session, _doc=step["_doc"])
+    step["_code"] = c
+    display.sequence(memory.session["sequence"])
+    if HAL.auto >= 0 and (request_input is None):
+        display.log(f"[HAL] Executing...", "Executing")
+        try:
+            run.execute(c, import_variable=memory.session)
+            print("Execution Completed with SIGNAL: ", STATE.get("SIGNAL", ""))
+        except Exception as err:
+            STATE["SIGNAL"] = f"Runtime Error: {type(e).__name__}: {str(err)}"
+            print("Execution Error: ", str(err))
+        display.log(f"[HAL] Execution completed with SIGNAL: {STATE['SIGNAL']}")
+        display.sequence(memory.session["sequence"])
+        return False
+    display.new_cell((f"# [HAL] Requesting user input:\n{request_input}\n\n" if request_input is not None else "") + f"# [HAL] Imports:\n{utils.get_exec_import(memory.session)}\n\n# [HAL] Code:\n{c}")
+    return True
+handlers["code"] = code_handler
+

clelandlab_hal-0.0.0/HAL/display.py

@@ -0,0 +1,61 @@
+import yaml
+import ipywidgets as widgets
+from IPython.display import display, Markdown
+from IPython.core.getipython import get_ipython
+
+log_output = widgets.Output(layout={'height': '300px', 'overflow_y': 'auto'})
+log_accordion = widgets.Accordion(children=[log_output], titles=["[HAL]"])
+sequence_accordion = widgets.Accordion()
+
+def get_markdown_output(content):
+    out = widgets.Output()
+    with out:
+        display(Markdown(content))
+    return out
+
+def init():
+    display(log_accordion)
+    display(sequence_accordion)
+
+def log(content, status="Idle"):
+    log_accordion.set_title(0, f"Status [HAL] {status}")
+    with log_output:
+        print(content)
+
+def show(content):
+    display(Markdown("---\n\n" + content + "\n\n---\n\n"))
+    return content
+
+def new_cell(content):
+    get_ipython().set_next_input(content, replace=False)
+
+def sequence(seq):
+    sequence_accordion.children = []
+    for i, step in enumerate(seq):
+        tab = widgets.Tab()
+        for key in step:
+            if key == "_type":
+                continue
+            content = step[key]
+            if "code" in key:
+                content = f"```python\n{content}\n```"
+            if key == "_doc":
+                content = f"```yaml\n{yaml.dump(content)}\n```"
+            tab.children += (get_markdown_output(content),)
+            tab.set_title(len(tab.children) - 1, key)
+        tab.selected_index = 1 if len(tab.children) > 1 else 0
+        sequence_accordion.children += (tab,)
+        sequence_accordion.set_title(i, f"sequence [{i}] {step.get('_type', '')}")
+
+def docs(doc_texts):
+    n = len(doc_texts)
+    out = widgets.Output()
+    def on_slider_change(change):
+        i = change['new']
+        out.clear_output()
+        with out:
+            display(Markdown(doc_texts[i]))
+    slider = widgets.IntSlider(value=0, min=0, max=n-1, step=1, description=f'Docs ({n}):', continuous_update=False)
+    slider.observe(on_slider_change, names='value')
+    on_slider_change({'new': 0})
+    display(slider, out)

clelandlab_hal-0.0.0/HAL/memory.py

@@ -0,0 +1,78 @@
+import time, json, gzip, hashlib, os, datetime
+import numpy as np
+from .display import log
+from .utils import add_embedding_cost, config
+
+session = {
+    "name": "HAL",
+    "cost": 0.0,
+    "sequence": [],
+    "STATE": {}
+}
+
+clent = None # gemini client
+
+data = {}
+
+# helper functions
+cos_sim = lambda v1, v2: np.dot(v1, v2) / (np.linalg.norm(v1) * np.linalg.norm(v2))
+def sha256str(s):
+    h = hashlib.sha256()
+    h.update(s.encode('utf-8'))
+    return h.hexdigest()
+def embed(content, task_type="retrieval_document"):
+    try:
+        model = "gemini-embedding-001"
+        add_embedding_cost(client.models.count_tokens(model=model, contents=content))
+        return client.models.embed_content(model=model, contents=content, config={"task_type": task_type}).embeddings[0].values
+    except:
+        return None
+
+# operations
+def load():
+    global data, mean_embedding
+    try:
+        with gzip.open(config["MEMORY_DATA_PATH"], 'rt') as f:
+            data = json.load(f)
+        m_time_timestamp = os.path.getmtime(config["MEMORY_DATA_PATH"])
+        m_time_datetime = datetime.datetime.fromtimestamp(m_time_timestamp)
+        log(f"[HAL] Memory loaded: {len(data)} documents (version {m_time_datetime})")
+    except:
+        data = {}
+    return data
+def save():
+    with gzip.open(config["MEMORY_DATA_PATH"], 'wt') as f:
+        json.dump(data, f)
+
+def add(content, meta={}):
+    doc_id = sha256str(content)
+    data_dict = {"content": content, "embedding": embed(content)}
+    meta["time"] = int(time.time())
+    data_dict.update(meta)
+    data[doc_id] = data_dict
+    return doc_id
+def get(doc_id):
+    global data
+    doc = dict(data[doc_id])
+    doc.update({"id": doc_id})
+    return doc
+def delete(doc_id):
+    del data[doc_id]
+
+# return a list of (doc_id, score)
+def search(q, maxn=5, cutoff_gradient=0.05, threshold=0.6, filter=None):
+    scores = []
+    score = 0
+    q_embedding = embed(q, task_type="retrieval_query")
+    for doc_id, data_dict in data.items():
+        if filter is not None and not filter(data_dict):
+            continue
+        score = cos_sim(q_embedding, np.array(data_dict['embedding']))
+        if score < threshold:
+            continue
+        scores.append((doc_id, score))
+    scores.sort(key=lambda x: x[1], reverse=True)
+    for i in range(min(maxn, len(scores) - 1)):
+        if scores[i][1] - scores[i+1][1] >= cutoff_gradient:
+            return scores[:(i+1)]
+    return scores[:maxn]

clelandlab_hal-0.0.0/HAL/run.py

@@ -0,0 +1,28 @@
+import re
+from . import memory
+from .utils import get_exec_import
+
+def execute(code, import_variable={ "name": "HAL" }):
+    STATE = memory.session["STATE"]
+    STATE["SIGNAL"] = ""
+    _code = get_exec_import(import_variable) + "\n\n" + code
+    INVOKE = lambda name: invoke(name, import_variable=import_variable)
+    exec(_code, { "STATE": STATE, "INVOKE": INVOKE }, { "STATE": STATE, "INVOKE": INVOKE })
+
+def invoke(name=None, import_variable={ "name": "HAL" }):
+    code = ""
+    if name is None:
+        name = -1
+    if isinstance(name, int):
+        step = memory.session["sequence"][name]
+        code = step.get("_code", "")
+    if isinstance(name, str):
+        docs = memory.search(name, filter=lambda d: "invoke" in d and d["invoke"])
+        if len(docs) == 0:
+            return
+        doc = memory.get(docs[0][0])
+        code_match = re.search(r"```python\n(.*?)\n```", doc["content"], re.DOTALL)
+        code = code_match.group(1) if code_match else ""
+    if code == "":
+        return
+    execute(code, import_variable=import_variable)

clelandlab_hal-0.0.0/HAL/utils.py

@@ -0,0 +1,56 @@
+from . import memory
+
+config = {}
+
+def docs2text(docs):
+    res = ""
+    for i, doc in enumerate(docs):
+        res += f"--- Document {i} ---\n\n{doc['content']}\n\n"
+    res += "--- End of Documents ---"
+    return res
+
+def sequence2text(sequence):
+    res = ""
+    for i, step in enumerate(sequence):
+        res += f"--- Step {i} ---\n\n"
+        for k, v in step.items():
+            if k[0] != "_":
+                res += f"{k}: {v}\n"
+        res += "\n"
+    res += "--- End of Steps ---"
+    return res
+
+def state_type2text(STATE):
+    s = ""
+    for k, v in STATE.items():
+        s += f"- `{k}`({type(v).__name__})\n"
+    return s
+
+evalStr = lambda s, var: eval(f"f'''{s}'''", None, var)
+
+get_exec_import = lambda var: evalStr(config["EXEC_IMPORT"], var)
+
+prices = {
+    "gemini-embedding-001": 0.15/1e6,
+    "gemini-3.1-pro-preview": (2/1e6, 12/1e6),
+    "gemini-3-flash-preview": (0.5/1e6, 3/1e6)
+}
+
+def add_embedding_cost(res):
+    total_cost = res.total_tokens * prices["gemini-embedding-001"]
+    memory.session["cost"] += total_cost
+    return total_cost
+
+def add_generative_cost(res):
+    v = res.model_version
+    u = res.usage_metadata
+    if v not in prices:
+        print(f"[HAL] Warning: model version {v} not found in prices list. Cost estimation will be inaccurate.")
+    p = prices.get(v, (0, 0))
+    input_token_count = u.prompt_token_count
+    output_token_count = u.total_token_count - u.prompt_token_count
+    total_cost = p[0] * input_token_count + p[1] * output_token_count
+    memory.session["cost"] += total_cost
+    if input_token_count > 2e5:
+        print(f"[HAL] Warning: input token count({input_token_count}) exceeds 200k tokens. Cost estimation will be inaccurate.")
+    return total_cost

clelandlab_hal-0.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cleland Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

clelandlab_hal-0.0.0/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: clelandlab-HAL
+Version: 0.0.0
+Summary: Heuristic Autonomous Lab
+Home-page: https://github.com/clelandlab/HAL
+Author: Cleland Lab
+Author-email: clelandlab@proton.me
+Project-URL: Source, https://github.com/clelandlab/HAL
+Project-URL: Tracker, https://github.com/clelandlab/HAL/issues
+Keywords: LLM,AI,quantum,experiment,measurement,qubit,control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai
+Requires-Dist: ipywidgets
+Requires-Dist: ipython
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# HAL
+
+Heuristic Autonomous Lab
+
+## Config
+
+Create a `config.json` with the following content:
+
+```json
+{
+  "GEMINI_API_KEY": "your gemini API key",
+  "MEMORY_DATA_PATH": "/path/to/the/memory/data.gz",
+  "EXEC_IMPORT": "import time, os, sys, json, yaml, scipy\nimport numpy as np\nimport matplotlib.pyplot as plt\n"
+}
+```
+
+## Get Started
+
+```python
+import HAL
+HAL.init() # initialization: loading memory, setting up display, etc.
+# HAL.auto = 3 # auto-execution: HAL will automatically execute up to 3 steps
+
+HAL.reset() # this reset HAL session
+HAL("Do something") # main interface: query HAL
+
+HAL() # continue without user input
+```
+
+## API
+
+```python
+# initialization
+HAL.init("Name", _config=None)
+
+# main interface
+HAL(query=None)
+
+# properties
+HAL.auto = 0
+HAL.session = {}
+
+# session operations
+HAL.reset()
+HAL.save(path="session.json")
+HAL.load(path="session.json")
+
+# memory operations
+HAL.search(query)
+HAL.memorize(content, meta={ "source": HAL.name })
+
+# low-level components
+HAL.memory
+HAL.display
+# Agents
+HAL.gather_document
+HAL.sort
+HAL.plan
+HAL.answer
+HAL.code
+```

clelandlab_hal-0.0.0/README.md

@@ -0,0 +1,61 @@
+# HAL
+
+Heuristic Autonomous Lab
+
+## Config
+
+Create a `config.json` with the following content:
+
+```json
+{
+  "GEMINI_API_KEY": "your gemini API key",
+  "MEMORY_DATA_PATH": "/path/to/the/memory/data.gz",
+  "EXEC_IMPORT": "import time, os, sys, json, yaml, scipy\nimport numpy as np\nimport matplotlib.pyplot as plt\n"
+}
+```
+
+## Get Started
+
+```python
+import HAL
+HAL.init() # initialization: loading memory, setting up display, etc.
+# HAL.auto = 3 # auto-execution: HAL will automatically execute up to 3 steps
+
+HAL.reset() # this reset HAL session
+HAL("Do something") # main interface: query HAL
+
+HAL() # continue without user input
+```
+
+## API
+
+```python
+# initialization
+HAL.init("Name", _config=None)
+
+# main interface
+HAL(query=None)
+
+# properties
+HAL.auto = 0
+HAL.session = {}
+
+# session operations
+HAL.reset()
+HAL.save(path="session.json")
+HAL.load(path="session.json")
+
+# memory operations
+HAL.search(query)
+HAL.memorize(content, meta={ "source": HAL.name })
+
+# low-level components
+HAL.memory
+HAL.display
+# Agents
+HAL.gather_document
+HAL.sort
+HAL.plan
+HAL.answer
+HAL.code
+```

clelandlab_hal-0.0.0/clelandlab_HAL.egg-info/PKG-INFO

@@ -0,0 +1,101 @@
+Metadata-Version: 2.4
+Name: clelandlab-HAL
+Version: 0.0.0
+Summary: Heuristic Autonomous Lab
+Home-page: https://github.com/clelandlab/HAL
+Author: Cleland Lab
+Author-email: clelandlab@proton.me
+Project-URL: Source, https://github.com/clelandlab/HAL
+Project-URL: Tracker, https://github.com/clelandlab/HAL/issues
+Keywords: LLM,AI,quantum,experiment,measurement,qubit,control
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.8, <4
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: google-genai
+Requires-Dist: ipywidgets
+Requires-Dist: ipython
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license-file
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# HAL
+
+Heuristic Autonomous Lab
+
+## Config
+
+Create a `config.json` with the following content:
+
+```json
+{
+  "GEMINI_API_KEY": "your gemini API key",
+  "MEMORY_DATA_PATH": "/path/to/the/memory/data.gz",
+  "EXEC_IMPORT": "import time, os, sys, json, yaml, scipy\nimport numpy as np\nimport matplotlib.pyplot as plt\n"
+}
+```
+
+## Get Started
+
+```python
+import HAL
+HAL.init() # initialization: loading memory, setting up display, etc.
+# HAL.auto = 3 # auto-execution: HAL will automatically execute up to 3 steps
+
+HAL.reset() # this reset HAL session
+HAL("Do something") # main interface: query HAL
+
+HAL() # continue without user input
+```
+
+## API
+
+```python
+# initialization
+HAL.init("Name", _config=None)
+
+# main interface
+HAL(query=None)
+
+# properties
+HAL.auto = 0
+HAL.session = {}
+
+# session operations
+HAL.reset()
+HAL.save(path="session.json")
+HAL.load(path="session.json")
+
+# memory operations
+HAL.search(query)
+HAL.memorize(content, meta={ "source": HAL.name })
+
+# low-level components
+HAL.memory
+HAL.display
+# Agents
+HAL.gather_document
+HAL.sort
+HAL.plan
+HAL.answer
+HAL.code
+```

clelandlab_hal-0.0.0/clelandlab_HAL.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+setup.py
+HAL/HAL_answer.py
+HAL/HAL_code.py
+HAL/HAL_gather_document.py
+HAL/HAL_plan.py
+HAL/HAL_sort.py
+HAL/VERSION
+HAL/__init__.py
+HAL/display.py
+HAL/memory.py
+HAL/run.py
+HAL/utils.py
+clelandlab_HAL.egg-info/PKG-INFO
+clelandlab_HAL.egg-info/SOURCES.txt
+clelandlab_HAL.egg-info/dependency_links.txt
+clelandlab_HAL.egg-info/requires.txt
+clelandlab_HAL.egg-info/top_level.txt

clelandlab_hal-0.0.0/clelandlab_HAL.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

clelandlab_hal-0.0.0/clelandlab_HAL.egg-info/requires.txt

@@ -0,0 +1,3 @@
+google-genai
+ipywidgets
+ipython

clelandlab_hal-0.0.0/clelandlab_HAL.egg-info/top_level.txt

@@ -0,0 +1 @@
+HAL

clelandlab_hal-0.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

clelandlab_hal-0.0.0/setup.py

@@ -0,0 +1,46 @@
+from setuptools import setup, find_packages
+import pathlib
+
+here = pathlib.Path(__file__).parent.resolve()
+def get_version(rel_path):
+    return (here / rel_path).read_text().strip()
+
+setup(
+    name="clelandlab-HAL",
+    version=get_version("HAL/VERSION"),
+    description="Heuristic Autonomous Lab",
+    long_description=(here / "README.md").read_text(encoding="utf-8"),
+    long_description_content_type="text/markdown",
+    url="https://github.com/clelandlab/HAL",
+    author="Cleland Lab",
+    author_email="clelandlab@proton.me",
+    classifiers=[
+        "Development Status :: 3 - Alpha",
+        "Intended Audience :: Developers",
+        "Topic :: Software Development :: Build Tools",
+        "License :: OSI Approved :: MIT License",
+        "Programming Language :: Python :: 3",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+        "Programming Language :: Python :: 3 :: Only",
+    ],
+    keywords="LLM,AI,quantum,experiment,measurement,qubit,control",
+    packages=find_packages(where="."),
+    python_requires=">=3.8, <4",
+    install_requires=[
+        "google-genai",
+        "ipywidgets",
+        "ipython"
+    ],
+    package_data={
+        "HAL": ["VERSION"],
+    },
+    include_package_data=True,
+    project_urls={
+        "Source": "https://github.com/clelandlab/HAL",
+        "Tracker": "https://github.com/clelandlab/HAL/issues",
+    },
+)