sylo-fieldbrain 0.1.0

package/scripts/fieldbrain_brain_restore.py

@@ -0,0 +1,49 @@
+#!/usr/bin/env python3
+"""Restore a soft-deleted brain document (logicscout_brain_restore tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.brain_service import restore_brain
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--path", required=True)
+    parser.add_argument("--scope", choices=("global", "project"), default="project")
+    parser.add_argument("--project-id", type=int, default=None)
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    if args.scope == "project" and args.project_id is None:
+        emit_error("--project-id is required when scope is project")
+
+    try:
+        with Session(get_engine()) as session:
+            result = restore_brain(
+                session,
+                scope=args.scope,
+                relative_path=args.path,
+                project_id=args.project_id,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    emit(
+        {
+            "ok": True,
+            "document": result,
+            "operator_chat": f"Restored brain {args.scope}:{args.path}.",
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_brain_revisions.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""List revision history for a brain document (logicscout_brain_revisions tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.brain_service import list_brain_revisions
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--path", required=True)
+    parser.add_argument("--scope", choices=("global", "project"), default="project")
+    parser.add_argument("--project-id", type=int, default=None)
+    parser.add_argument("--limit", type=int, default=20)
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    if args.scope == "project" and args.project_id is None:
+        emit_error("--project-id is required when scope is project")
+
+    try:
+        with Session(get_engine()) as session:
+            revisions = list_brain_revisions(
+                session,
+                scope=args.scope,
+                relative_path=args.path,
+                project_id=args.project_id,
+                limit=args.limit,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    emit(
+        {
+            "ok": True,
+            "path": args.path,
+            "scope": args.scope,
+            "revisions": revisions,
+            "count": len(revisions),
+            "operator_chat": f"{len(revisions)} revision(s) for brain {args.scope}:{args.path}.",
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_brain_write.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""Write/update brain markdown (logicscout_brain_write tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.brain_service import write_brain_markdown
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--path", required=True, help="Relative brain path, e.g. gotchas/conveyor_jam.md")
+    parser.add_argument("--content", required=True, help="Markdown body (full file when mode=replace)")
+    parser.add_argument(
+        "--scope",
+        choices=("global", "project"),
+        default="project",
+        help="global org brain or project brain",
+    )
+    parser.add_argument("--project-id", type=int, default=None, help="Required when scope=project")
+    parser.add_argument(
+        "--mode",
+        choices=("replace", "append"),
+        default="replace",
+        help="replace entire file or append to existing",
+    )
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    if args.scope == "project" and args.project_id is None:
+        emit_error("--project-id is required when scope is project")
+
+    try:
+        with Session(get_engine()) as session:
+            result = write_brain_markdown(
+                session,
+                scope=args.scope,
+                relative_path=args.path,
+                content=args.content,
+                project_id=args.project_id,
+                mode=args.mode,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    action = "Created" if result.get("created") else "Updated"
+    emit(
+        {
+            "ok": True,
+            **result,
+            "operator_chat": (
+                f"{action} brain {result['scope']}:{result['relative_path']} "
+                f"({result['size_bytes']} bytes, mode={result['mode']})."
+            ),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_document_attach.py

@@ -0,0 +1,81 @@
+#!/usr/bin/env python3
+"""Attach existing doc or register new file path (logicscout_document_attach tool)."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.document_service import attach_document_to_project, register_document_from_path
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--document-id", type=int, default=None, help="Attach existing document by id")
+    parser.add_argument("--file-path", default="", help="Register a new file (copied into shared storage)")
+    parser.add_argument("--project-id", type=int, default=None, help="Target project id")
+    parser.add_argument(
+        "--scope",
+        choices=("global", "project"),
+        default="project",
+        help="Scope when registering a new file (default project)",
+    )
+    parser.add_argument("--title", default="", help="Optional title when registering a file")
+    parser.add_argument("--role", default="reference", help="Link role: reference or schematic")
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    has_doc = args.document_id is not None
+    has_file = bool(args.file_path.strip())
+    if has_doc == has_file:
+        emit_error("Provide exactly one of --document-id or --file-path")
+
+    try:
+        with Session(get_engine()) as session:
+            if has_file:
+                result = register_document_from_path(
+                    session,
+                    Path(args.file_path.strip()),
+                    scope=args.scope,
+                    project_id=args.project_id,
+                    title=args.title or None,
+                    attach=args.project_id is not None,
+                )
+                doc = result["document"]
+                chat = (
+                    f"Registered document #{doc['id']}: {doc['title']} "
+                    f"(scope={doc['scope']}, created={result['created']})."
+                )
+                if result.get("linked"):
+                    chat += f" Linked to project {args.project_id}."
+                emit({"ok": True, **result, "operator_chat": chat})
+            else:
+                if args.project_id is None:
+                    emit_error("--project-id is required when attaching an existing document")
+                result = attach_document_to_project(
+                    session,
+                    args.project_id,
+                    args.document_id,
+                    role=args.role,
+                )
+                doc = result["document"]
+                verb = "Attached" if not result.get("already_linked") else "Already linked"
+                emit(
+                    {
+                        "ok": True,
+                        **result,
+                        "operator_chat": f"{verb} document #{doc['id']} ({doc['title']}) to project {args.project_id}.",
+                    }
+                )
+    except ValueError as exc:
+        emit_error(str(exc))
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_document_catalog.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""Catalog a library document after the agent reads it with Sylo reader skills."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.document_catalog import catalog_document
+from services.document_formats import READER_HINTS, reader_hint_for_ext
+from services.document_service import register_document_from_path
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--document-id", type=int, default=None, help="Existing document id")
+    parser.add_argument(
+        "--file-path",
+        default="",
+        help="Register this file first (global or project scope), then catalog",
+    )
+    parser.add_argument(
+        "--description",
+        required=True,
+        help="Agent-written catalog summary (what this file is and when to use it)",
+    )
+    parser.add_argument("--title", default="", help="Optional display title")
+    parser.add_argument("--category", default="", help="manual, datasheet, requirements, email, howto, image, …")
+    parser.add_argument("--tags", default="", help="Comma-separated or JSON array")
+    parser.add_argument("--manufacturer", default="")
+    parser.add_argument("--model", default="")
+    parser.add_argument("--version", default="")
+    parser.add_argument(
+        "--outline-json",
+        default="",
+        help='Optional JSON array: [{"level":1,"title":"Section","page":0}]',
+    )
+    parser.add_argument(
+        "--scope",
+        choices=("global", "project"),
+        default="global",
+        help="When using --file-path (default global library)",
+    )
+    parser.add_argument("--project-id", type=int, default=None)
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    has_doc = args.document_id is not None
+    has_file = bool(args.file_path.strip())
+    if has_doc == has_file:
+        emit_error("Provide exactly one of --document-id or --file-path")
+
+    outline: list[dict] | None = None
+    if args.outline_json.strip():
+        try:
+            parsed = json.loads(args.outline_json)
+            if not isinstance(parsed, list):
+                emit_error("--outline-json must be a JSON array")
+            outline = parsed
+        except json.JSONDecodeError as exc:
+            emit_error(f"Invalid --outline-json: {exc}")
+
+    try:
+        with Session(get_engine()) as session:
+            if has_file:
+                path = Path(args.file_path.strip()).expanduser().resolve()
+                ext = path.suffix.lower()
+                reg = register_document_from_path(
+                    session,
+                    path,
+                    scope=args.scope,
+                    project_id=args.project_id,
+                    title=args.title or None,
+                    category=args.category or "other",
+                    attach=args.project_id is not None,
+                )
+                doc_id = int(reg["document"]["id"])
+                reader = reader_hint_for_ext(ext)
+            else:
+                doc_id = int(args.document_id)
+                reader = None
+
+            result = catalog_document(
+                session,
+                doc_id,
+                description=args.description,
+                tags=args.tags or None,
+                category=args.category or None,
+                title=args.title or None,
+                manufacturer=args.manufacturer or None,
+                model=args.model or None,
+                version=args.version or None,
+                outline=outline,
+                project_id=args.project_id,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+    except Exception as exc:
+        emit_error(f"Catalog failed: {exc}")
+
+    doc = result["document"]
+    lines = [
+        f"Cataloged document #{doc['id']}: {doc['title']} (category={doc['category']}).",
+        f"Indexed {result.get('chunks_indexed', 0)} search chunk(s); "
+        f"{result.get('embeddings_written', 0)} embedding(s).",
+        "Deep read later with the matching Sylo reader — not stored as full-text chunks.",
+    ]
+    if reader:
+        lines.insert(1, f"Reader for this type: {reader}")
+    emit(
+        {
+            "ok": True,
+            **result,
+            "reader_hints": READER_HINTS,
+            "operator_chat": "\n".join(lines),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_document_ingest.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Ingest PDF/text: extract, chunk, index, embed (logicscout_document_ingest tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.document_ingest import ingest_document_file
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--file-path", required=True, help="Path to PDF or .txt on disk")
+    parser.add_argument(
+        "--scope",
+        choices=("global", "project"),
+        default="project",
+        help="global library or project-local document",
+    )
+    parser.add_argument("--project-id", type=int, default=None, help="Required when scope=project")
+    parser.add_argument("--title", default="", help="Optional document title")
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    if args.scope == "project" and args.project_id is None:
+        emit_error("--project-id is required when scope is project")
+
+    try:
+        with Session(get_engine()) as session:
+            result = ingest_document_file(
+                session,
+                args.file_path,
+                scope=args.scope,
+                project_id=args.project_id,
+                title=args.title or None,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+    except Exception as exc:
+        emit_error(f"Ingest failed: {exc}")
+
+    emit(
+        {
+            "ok": True,
+            **result,
+            "operator_chat": (
+                f"Ingested document #{result['document_id']}: {result['title']}. "
+                f"{result['chunks_indexed']} chunk(s) indexed, "
+                f"{result['embeddings_written']} embedding(s) written."
+            ),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_document_list.py

@@ -0,0 +1,67 @@
+#!/usr/bin/env python3
+"""List global or project documents (logicscout_document_list tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.document_service import list_documents_for_project, list_global_documents
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "--scope",
+        choices=("global", "project"),
+        default="global",
+        help="global library or project-attached documents",
+    )
+    parser.add_argument("--project-id", type=int, default=None, help="Required when scope=project")
+    parser.add_argument("--category", default="", help="Filter global docs by category")
+    parser.add_argument("--search", default="", help="Filter global docs by title/filename")
+    parser.add_argument("--limit", type=int, default=200, help="Max global results (default 200)")
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    if args.scope == "project" and args.project_id is None:
+        emit_error("--project-id is required when scope is project")
+
+    with Session(get_engine()) as session:
+        if args.scope == "global":
+            documents = list_global_documents(
+                session,
+                category=args.category or None,
+                search=args.search or None,
+                limit=args.limit,
+            )
+        else:
+            documents = list_documents_for_project(session, args.project_id)
+
+    lines = []
+    for d in documents:
+        role = f" role={d['link_role']}" if d.get("link_role") else ""
+        lines.append(f"#{d['id']} {d['title']} ({d['scope']}){role}")
+
+    emit(
+        {
+            "ok": True,
+            "scope": args.scope,
+            "project_id": args.project_id,
+            "count": len(documents),
+            "documents": documents,
+            "operator_chat": (
+                f"Listed {len(documents)} document(s) ({args.scope}).\n"
+                + ("\n".join(lines) if lines else "(none)")
+            ),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_document_promote.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+"""Promote a project-local document to the global library (fieldbrain_document_promote tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.document_service import promote_document_to_global
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--document-id", type=int, required=True, help="Document id to promote")
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    try:
+        with Session(get_engine()) as session:
+            result = promote_document_to_global(session, args.document_id)
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    doc = result["document"]
+    if result.get("promoted"):
+        chat = (
+            f"Promoted document #{doc['id']} ({doc['title']}) to the global library. "
+            f"It now appears in global search; the link to project "
+            f"{result.get('previous_project_id')} is kept."
+        )
+    else:
+        chat = f"Document #{doc['id']} ({doc['title']}) is already in the global library."
+
+    emit({"ok": True, **result, "operator_chat": chat})
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_log_create.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Create a maintenance log entry (logicscout_log_create tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.maintenance_log_service import create_log_entry
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--title", required=True, help="Short summary title")
+    parser.add_argument("--body", required=True, help="Full log body / notes")
+    parser.add_argument("--project-id", type=int, default=None, help="Optional project id")
+    parser.add_argument("--fault-code", default="", help="Optional fault/alarm code")
+    parser.add_argument("--equipment-tag", default="", help="Optional PLC/HMI tag or asset id")
+    parser.add_argument("--logged-by", default="", help="Optional attribution string")
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    try:
+        with Session(get_engine()) as session:
+            entry = create_log_entry(
+                session,
+                title=args.title,
+                body=args.body,
+                project_id=args.project_id,
+                fault_code=args.fault_code or None,
+                equipment_tag=args.equipment_tag or None,
+                logged_by=args.logged_by or None,
+            )
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    emit(
+        {
+            "ok": True,
+            "entry": entry,
+            "operator_chat": (
+                f"Logged maintenance entry #{entry['id']}: {entry['title']}"
+                + (f" (project {entry['project_id']})" if entry.get("project_id") else "")
+            ),
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_log_delete.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Soft-delete a maintenance log entry (logicscout_log_delete tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.maintenance_log_service import soft_delete_log_entry
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--entry-id", type=int, required=True)
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    try:
+        with Session(get_engine()) as session:
+            result = soft_delete_log_entry(session, args.entry_id)
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    emit(
+        {
+            "ok": True,
+            **result,
+            "operator_chat": f"Soft-deleted maintenance log entry {args.entry_id} (revision saved).",
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()

package/scripts/fieldbrain_log_restore.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+"""Restore a soft-deleted maintenance log entry (logicscout_log_restore tool)."""
+
+from __future__ import annotations
+
+import argparse
+
+from _db_lib import get_engine, verify_schema_version
+from _json_out import emit, emit_error
+from services.maintenance_log_service import restore_log_entry
+from sqlalchemy.orm import Session
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--entry-id", type=int, required=True)
+    args = parser.parse_args()
+
+    ok, msg = verify_schema_version()
+    if not ok:
+        emit_error(msg)
+
+    try:
+        with Session(get_engine()) as session:
+            result = restore_log_entry(session, args.entry_id)
+    except ValueError as exc:
+        emit_error(str(exc))
+
+    emit(
+        {
+            "ok": True,
+            "entry": result,
+            "operator_chat": f"Restored maintenance log entry {args.entry_id}: {result['title']}",
+        }
+    )
+
+
+if __name__ == "__main__":
+    main()