research-panel 3.1.1__py3-none-any.whl

research/__init__.py

@@ -0,0 +1,253 @@
+"""research — project-local research memory: questions → experiments → runs → findings → decisions → checkpoints.
+
+Python API (all functions operate on the project containing the current directory,
+or $RESEARCH_ROOT, unless you pass `project=Project(...)`):
+
+    import research
+    research.get_resume_context()
+    q = research.create_question("Does alpha affect error?")
+    e = research.create_experiment("alpha sweep", question=q["id"], hypothesis="…", parameters={"alpha": [0.1, 0.5]})
+    run = research.create_run(e["id"], command="python sweep.py --alpha 0.1", parameters={"alpha": 0.1})
+    research.log_metric("rmse", 0.12, run=run["id"])       # inside a `research run exec` job: run is implicit
+    research.register_artifact("outputs/plot.png", run=run["id"], description="error vs alpha")
+    research.create_finding("alpha=0.5 best tradeoff", supports=[e["id"], run["id"]], confidence="medium")
+    research.create_decision("Use alpha=0.5 as baseline", supporting_findings=["F-001"])
+    research.create_checkpoint()
+
+    # Plans and Tasks (Phase 0)
+    plan = research.create_plan("Reproduce paper X", objective="Reproduce Table 1")
+    t1 = research.create_task(plan["id"], "Implement baseline model", goal="...")
+    t2 = research.create_task(plan["id"], "Run experiments", depends_on=[t1["id"]])
+    research.start_task(t1["id"])
+    research.complete_task(t1["id"], result="baseline implemented in model.py")
+"""
+from __future__ import annotations
+
+import functools
+from typing import Any, Dict, List, Optional
+
+from . import context as _context
+from . import plans as _plans
+from . import runs as _runs
+from . import services as _services
+from . import views as _views
+from .store import Project, find_root
+from .util import BudgetExceeded, NotFound, NotInitialized, ResearchError
+
+__version__ = "3.1.1"
+
+__all__ = [
+    "Project", "ResearchError", "BudgetExceeded", "NotFound", "NotInitialized", "init", "open_project",
+    "get_project_context", "get_resume_context", "list_questions", "create_question", "update_question",
+    "create_experiment", "create_variant", "get_experiment", "list_experiments", "update_experiment",
+    "set_status", "synthesize", "set_baseline",
+    "create_run", "attach_run", "update_run", "get_run", "list_runs", "exec_run", "submit_run", "cancel_run",
+    "register_artifact", "list_artifacts", "log_metric",
+    "create_finding", "update_finding", "list_findings", "supersede_finding",
+    "create_decision", "list_decisions", "create_checkpoint", "checkpoint_draft", "list_checkpoints",
+    "create_note", "list_notes", "list_skills", "show", "regenerate_context",
+    # Phase 0: Plans and Tasks
+    "create_plan", "update_plan", "list_plans", "get_plan",
+    "create_task", "update_task", "list_tasks", "get_task", "get_next_ready_task",
+    "start_task", "complete_task", "block_task", "task_context",
+    "release_task", "add_task_note", "verify_task", "review_finding", "search", "compare_runs", "sweep_run",
+    "write_report", "dispatch", "list_skills_full", "add_skills", "remove_skill", "update_skills", "link_skills",
+]
+
+
+def init(root: str = ".", name: Optional[str] = None, goal: Optional[str] = None) -> Project:
+    return Project.init(root, name=name, goal=goal)
+
+
+def open_project(root: Optional[str] = None) -> Project:
+    return Project(root) if root else Project.find()
+
+
+def _with_project(fn):
+    @functools.wraps(fn)
+    def wrapper(*args, project: Optional[Project] = None, **kwargs):
+        if project is not None:
+            return fn(project, *args, **kwargs)
+        p = Project.find()
+        try:
+            return fn(p, *args, **kwargs)
+        finally:
+            p.close()
+    return wrapper
+
+
+# ------------------------------------------------------------------------------------ context
+@_with_project
+def get_resume_context(p: Project) -> Dict[str, Any]:
+    return _context.resume_context(p)
+
+
+get_project_context = get_resume_context
+
+
+@_with_project
+def regenerate_context(p: Project) -> str:
+    return _context.write_current_md(p)
+
+
+@_with_project
+def show(p: Project, id_: str) -> Dict[str, Any]:
+    return _views.show(p, id_)
+
+
+# ------------------------------------------------------------------------------------ questions
+@_with_project
+def list_questions(p: Project, status: Optional[str] = None) -> List[Dict[str, Any]]:
+    return p.list("question", "status=?" if status else "", (status,) if status else ())
+
+
+create_question = _with_project(_services.create_question)
+update_question = _with_project(_services.update_question)
+
+# ------------------------------------------------------------------------------------ experiments
+create_experiment = _with_project(_services.create_experiment)
+create_variant = _with_project(_services.create_variant)
+update_experiment = _with_project(_services.update_experiment)
+set_status = _with_project(_services.set_status)
+synthesize = _with_project(_services.synthesize)
+set_baseline = _with_project(_services.set_baseline)
+
+
+@_with_project
+def get_experiment(p: Project, exp_id: str) -> Dict[str, Any]:
+    return _views.experiment_detail(p, exp_id)
+
+
+@_with_project
+def list_experiments(p: Project, status: Optional[str] = None, question: Optional[str] = None) -> List[Dict[str, Any]]:
+    where, args = [], []
+    if status:
+        where.append("status=?")
+        args.append(status)
+    if question:
+        from .schema import normalize_id
+        where.append("question_id=?")
+        args.append(normalize_id(question, "Q"))
+    return p.list("experiment", " AND ".join(where), tuple(args))
+
+
+# ------------------------------------------------------------------------------------ runs
+create_run = _with_project(_runs.create_run)
+attach_run = _with_project(_runs.attach_run)
+update_run = _with_project(_runs.update_run)
+get_run = _with_project(_runs.get_run)
+list_runs = _with_project(_runs.list_runs)
+exec_run = _with_project(_runs.exec_run)
+submit_run = _with_project(_runs.submit_run)
+cancel_run = _with_project(_runs.cancel_run)
+list_artifacts = _with_project(_runs.list_artifacts)
+
+
+def log_metric(name: str, value: Any, step: Optional[int] = None, unit: Optional[str] = None,
+               run: Optional[str] = None, experiment: Optional[str] = None,
+               project: Optional[Project] = None) -> Dict[str, Any]:
+    """Log a metric. Inside a `research run` job (RESEARCH_RUN_DIR set) this only appends to the
+    run directory — safe on SLURM compute nodes, no database access."""
+    if run is None and experiment is None and project is None and _runs.in_job_run_dir():
+        return _runs.job_log_metric(name, value, step, unit)
+    return _with_project(_runs.log_metric)(name, value, step, unit, run, experiment, project=project)
+
+
+def register_artifact(path: str, run: Optional[str] = None, experiment: Optional[str] = None,
+                      name: Optional[str] = None, type: Optional[str] = None,
+                      description: Optional[str] = None, tags: Any = None,
+                      project: Optional[Project] = None, **kw: Any) -> Dict[str, Any]:
+    """Register a file/dir by reference. Inside a running job this is recorded in the run dir
+    and ingested (assigned an A-id) the next time the project is synced."""
+    if run is None and experiment is None and project is None and _runs.in_job_run_dir():
+        return _runs.job_register_artifact(path, name, description, type, tags)
+    return _with_project(_runs.register_artifact)(path, run, experiment, name, type, description, tags,
+                                                  project=project, **kw)
+
+
+# ------------------------------------------------------------------------------------ findings/decisions
+create_finding = _with_project(_services.create_finding)
+update_finding = _with_project(_services.update_finding)
+supersede_finding = _with_project(_services.supersede_finding)
+create_decision = _with_project(_services.create_decision)
+
+
+@_with_project
+def list_findings(p: Project, status: Optional[str] = None, kind: Optional[str] = None) -> List[Dict[str, Any]]:
+    where, args = [], []
+    if status:
+        where.append("status=?")
+        args.append(status)
+    if kind:
+        where.append("kind=?")
+        args.append(kind)
+    return p.list("finding", " AND ".join(where), tuple(args))
+
+
+@_with_project
+def list_decisions(p: Project, status: Optional[str] = None) -> List[Dict[str, Any]]:
+    return p.list("decision", "status=?" if status else "", (status,) if status else ())
+
+
+# ------------------------------------------------------------------------------------ checkpoints/notes/skills
+create_checkpoint = _with_project(_context.create_checkpoint)
+checkpoint_draft = _with_project(_context.checkpoint_draft)
+
+
+@_with_project
+def list_checkpoints(p: Project) -> List[Dict[str, Any]]:
+    return p.list("checkpoint", order="created_at DESC, id DESC")
+
+
+create_note = _with_project(_services.create_note)
+list_notes = _with_project(_services.list_notes)
+list_skills = _with_project(_services.list_skills)
+
+
+# ------------------------------------------------------------------------------------ plans/tasks (Phase 0)
+create_plan = _with_project(_plans.create_plan)
+update_plan = _with_project(_plans.update_plan)
+list_plans = _with_project(_plans.list_plans)
+create_task = _with_project(_plans.create_task)
+update_task = _with_project(_plans.update_task)
+list_tasks = _with_project(_plans.list_tasks)
+start_task = _with_project(_plans.start_task)
+complete_task = _with_project(_plans.complete_task)
+block_task = _with_project(_plans.block_task)
+get_next_ready_task = _with_project(_plans.get_next_ready_task)
+task_context = _with_project(_plans.task_context)
+release_task = _with_project(_plans.release_task)
+add_task_note = _with_project(_plans.add_task_note)
+
+# ------------------------------------------------------------------------------------ verification, retrieval, agents
+from . import agents as _agents  # noqa: E402
+from . import compare as _compare  # noqa: E402
+from . import report as _report  # noqa: E402
+from . import search as _search  # noqa: E402
+from . import skills as _skills  # noqa: E402
+from . import verification as _verification  # noqa: E402
+
+verify_task = _with_project(_verification.verify_task)
+review_finding = _with_project(_verification.review_finding)
+search = _with_project(_search.search)
+compare_runs = _with_project(_compare.compare_runs)
+sweep_run = _with_project(_runs.sweep_run)
+write_report = _with_project(_report.write_report)
+dispatch = _with_project(_agents.dispatch)
+list_skills_full = _with_project(_skills.list_skills)
+add_skills = _with_project(_skills.add_skills)
+remove_skill = _with_project(_skills.remove_skill)
+update_skills = _with_project(_skills.update_skills)
+link_skills = _with_project(_skills.link_skills)
+
+
+@_with_project
+def get_plan(p: Project, plan_id: str) -> Dict[str, Any]:
+    """Get plan with all its tasks and summary statistics."""
+    return _plans.get_plan_with_tasks(p, plan_id)
+
+
+@_with_project
+def get_task(p: Project, task_id: str) -> Dict[str, Any]:
+    """Get task with resolved dependencies and readiness status."""
+    return _plans.get_task_with_deps(p, task_id)

research/_vendor/yaml/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2017-2021 Ingy döt Net
+Copyright (c) 2006-2016 Kirill Simonov
+
+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.

research/_vendor/yaml/__init__.py

@@ -0,0 +1,390 @@
+
+from .error import *
+
+from .tokens import *
+from .events import *
+from .nodes import *
+
+from .loader import *
+from .dumper import *
+
+__version__ = '6.0.3'
+try:
+    from .cyaml import *
+    __with_libyaml__ = True
+except ImportError:
+    __with_libyaml__ = False
+
+import io
+
+#------------------------------------------------------------------------------
+# XXX "Warnings control" is now deprecated. Leaving in the API function to not
+# break code that uses it.
+#------------------------------------------------------------------------------
+def warnings(settings=None):
+    if settings is None:
+        return {}
+
+#------------------------------------------------------------------------------
+def scan(stream, Loader=Loader):
+    """
+    Scan a YAML stream and produce scanning tokens.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_token():
+            yield loader.get_token()
+    finally:
+        loader.dispose()
+
+def parse(stream, Loader=Loader):
+    """
+    Parse a YAML stream and produce parsing events.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_event():
+            yield loader.get_event()
+    finally:
+        loader.dispose()
+
+def compose(stream, Loader=Loader):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding representation tree.
+    """
+    loader = Loader(stream)
+    try:
+        return loader.get_single_node()
+    finally:
+        loader.dispose()
+
+def compose_all(stream, Loader=Loader):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding representation trees.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_node():
+            yield loader.get_node()
+    finally:
+        loader.dispose()
+
+def load(stream, Loader):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+    """
+    loader = Loader(stream)
+    try:
+        return loader.get_single_data()
+    finally:
+        loader.dispose()
+
+def load_all(stream, Loader):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+    """
+    loader = Loader(stream)
+    try:
+        while loader.check_data():
+            yield loader.get_data()
+    finally:
+        loader.dispose()
+
+def full_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve all tags except those known to be
+    unsafe on untrusted input.
+    """
+    return load(stream, FullLoader)
+
+def full_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve all tags except those known to be
+    unsafe on untrusted input.
+    """
+    return load_all(stream, FullLoader)
+
+def safe_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve only basic YAML tags. This is known
+    to be safe for untrusted input.
+    """
+    return load(stream, SafeLoader)
+
+def safe_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve only basic YAML tags. This is known
+    to be safe for untrusted input.
+    """
+    return load_all(stream, SafeLoader)
+
+def unsafe_load(stream):
+    """
+    Parse the first YAML document in a stream
+    and produce the corresponding Python object.
+
+    Resolve all tags, even those known to be
+    unsafe on untrusted input.
+    """
+    return load(stream, UnsafeLoader)
+
+def unsafe_load_all(stream):
+    """
+    Parse all YAML documents in a stream
+    and produce corresponding Python objects.
+
+    Resolve all tags, even those known to be
+    unsafe on untrusted input.
+    """
+    return load_all(stream, UnsafeLoader)
+
+def emit(events, stream=None, Dumper=Dumper,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None):
+    """
+    Emit YAML parsing events into a stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        stream = io.StringIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break)
+    try:
+        for event in events:
+            dumper.emit(event)
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def serialize_all(nodes, stream=None, Dumper=Dumper,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None,
+        encoding=None, explicit_start=None, explicit_end=None,
+        version=None, tags=None):
+    """
+    Serialize a sequence of representation trees into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        if encoding is None:
+            stream = io.StringIO()
+        else:
+            stream = io.BytesIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break,
+            encoding=encoding, version=version, tags=tags,
+            explicit_start=explicit_start, explicit_end=explicit_end)
+    try:
+        dumper.open()
+        for node in nodes:
+            dumper.serialize(node)
+        dumper.close()
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def serialize(node, stream=None, Dumper=Dumper, **kwds):
+    """
+    Serialize a representation tree into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    return serialize_all([node], stream, Dumper=Dumper, **kwds)
+
+def dump_all(documents, stream=None, Dumper=Dumper,
+        default_style=None, default_flow_style=False,
+        canonical=None, indent=None, width=None,
+        allow_unicode=None, line_break=None,
+        encoding=None, explicit_start=None, explicit_end=None,
+        version=None, tags=None, sort_keys=True):
+    """
+    Serialize a sequence of Python objects into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    getvalue = None
+    if stream is None:
+        if encoding is None:
+            stream = io.StringIO()
+        else:
+            stream = io.BytesIO()
+        getvalue = stream.getvalue
+    dumper = Dumper(stream, default_style=default_style,
+            default_flow_style=default_flow_style,
+            canonical=canonical, indent=indent, width=width,
+            allow_unicode=allow_unicode, line_break=line_break,
+            encoding=encoding, version=version, tags=tags,
+            explicit_start=explicit_start, explicit_end=explicit_end, sort_keys=sort_keys)
+    try:
+        dumper.open()
+        for data in documents:
+            dumper.represent(data)
+        dumper.close()
+    finally:
+        dumper.dispose()
+    if getvalue:
+        return getvalue()
+
+def dump(data, stream=None, Dumper=Dumper, **kwds):
+    """
+    Serialize a Python object into a YAML stream.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all([data], stream, Dumper=Dumper, **kwds)
+
+def safe_dump_all(documents, stream=None, **kwds):
+    """
+    Serialize a sequence of Python objects into a YAML stream.
+    Produce only basic YAML tags.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all(documents, stream, Dumper=SafeDumper, **kwds)
+
+def safe_dump(data, stream=None, **kwds):
+    """
+    Serialize a Python object into a YAML stream.
+    Produce only basic YAML tags.
+    If stream is None, return the produced string instead.
+    """
+    return dump_all([data], stream, Dumper=SafeDumper, **kwds)
+
+def add_implicit_resolver(tag, regexp, first=None,
+        Loader=None, Dumper=Dumper):
+    """
+    Add an implicit scalar detector.
+    If an implicit scalar value matches the given regexp,
+    the corresponding tag is assigned to the scalar.
+    first is a sequence of possible initial characters or None.
+    """
+    if Loader is None:
+        loader.Loader.add_implicit_resolver(tag, regexp, first)
+        loader.FullLoader.add_implicit_resolver(tag, regexp, first)
+        loader.UnsafeLoader.add_implicit_resolver(tag, regexp, first)
+    else:
+        Loader.add_implicit_resolver(tag, regexp, first)
+    Dumper.add_implicit_resolver(tag, regexp, first)
+
+def add_path_resolver(tag, path, kind=None, Loader=None, Dumper=Dumper):
+    """
+    Add a path based resolver for the given tag.
+    A path is a list of keys that forms a path
+    to a node in the representation tree.
+    Keys can be string values, integers, or None.
+    """
+    if Loader is None:
+        loader.Loader.add_path_resolver(tag, path, kind)
+        loader.FullLoader.add_path_resolver(tag, path, kind)
+        loader.UnsafeLoader.add_path_resolver(tag, path, kind)
+    else:
+        Loader.add_path_resolver(tag, path, kind)
+    Dumper.add_path_resolver(tag, path, kind)
+
+def add_constructor(tag, constructor, Loader=None):
+    """
+    Add a constructor for the given tag.
+    Constructor is a function that accepts a Loader instance
+    and a node object and produces the corresponding Python object.
+    """
+    if Loader is None:
+        loader.Loader.add_constructor(tag, constructor)
+        loader.FullLoader.add_constructor(tag, constructor)
+        loader.UnsafeLoader.add_constructor(tag, constructor)
+    else:
+        Loader.add_constructor(tag, constructor)
+
+def add_multi_constructor(tag_prefix, multi_constructor, Loader=None):
+    """
+    Add a multi-constructor for the given tag prefix.
+    Multi-constructor is called for a node if its tag starts with tag_prefix.
+    Multi-constructor accepts a Loader instance, a tag suffix,
+    and a node object and produces the corresponding Python object.
+    """
+    if Loader is None:
+        loader.Loader.add_multi_constructor(tag_prefix, multi_constructor)
+        loader.FullLoader.add_multi_constructor(tag_prefix, multi_constructor)
+        loader.UnsafeLoader.add_multi_constructor(tag_prefix, multi_constructor)
+    else:
+        Loader.add_multi_constructor(tag_prefix, multi_constructor)
+
+def add_representer(data_type, representer, Dumper=Dumper):
+    """
+    Add a representer for the given type.
+    Representer is a function accepting a Dumper instance
+    and an instance of the given data type
+    and producing the corresponding representation node.
+    """
+    Dumper.add_representer(data_type, representer)
+
+def add_multi_representer(data_type, multi_representer, Dumper=Dumper):
+    """
+    Add a representer for the given type.
+    Multi-representer is a function accepting a Dumper instance
+    and an instance of the given data type or subtype
+    and producing the corresponding representation node.
+    """
+    Dumper.add_multi_representer(data_type, multi_representer)
+
+class YAMLObjectMetaclass(type):
+    """
+    The metaclass for YAMLObject.
+    """
+    def __init__(cls, name, bases, kwds):
+        super(YAMLObjectMetaclass, cls).__init__(name, bases, kwds)
+        if 'yaml_tag' in kwds and kwds['yaml_tag'] is not None:
+            if isinstance(cls.yaml_loader, list):
+                for loader in cls.yaml_loader:
+                    loader.add_constructor(cls.yaml_tag, cls.from_yaml)
+            else:
+                cls.yaml_loader.add_constructor(cls.yaml_tag, cls.from_yaml)
+
+            cls.yaml_dumper.add_representer(cls, cls.to_yaml)
+
+class YAMLObject(metaclass=YAMLObjectMetaclass):
+    """
+    An object that can dump itself to a YAML stream
+    and load itself from a YAML stream.
+    """
+
+    __slots__ = ()  # no direct instantiation, so allow immutable subclasses
+
+    yaml_loader = [Loader, FullLoader, UnsafeLoader]
+    yaml_dumper = Dumper
+
+    yaml_tag = None
+    yaml_flow_style = None
+
+    @classmethod
+    def from_yaml(cls, loader, node):
+        """
+        Convert a representation node to a Python object.
+        """
+        return loader.construct_yaml_object(node, cls)
+
+    @classmethod
+    def to_yaml(cls, dumper, data):
+        """
+        Convert a Python object to a representation node.
+        """
+        return dumper.represent_yaml_object(cls.yaml_tag, data, cls,
+                flow_style=cls.yaml_flow_style)
+