mfcli 0.2.0__py3-none-any.whl

mfcli/constants/file_types.py

@@ -0,0 +1,189 @@
+from typing import Literal, Dict
+
+from mfcli.constants.base_enum import BaseEnum
+
+FILE_SUBTYPE_UNKNOWN = "UNKNOWN"
+
+
+class FileTypes(BaseEnum):
+    CSV = 1
+    ASC = 2
+    NET = 3
+    CIR = 4
+    PDF = 5
+
+
+class FileSubtypes(BaseEnum):
+    BOM = 1
+    PADS_PCB_ASCII = 2
+    KICAD_LEGACY_NET = 3
+    KICAD_SPICE = 4
+    SCHEMATIC = 5
+    ERRATA = 6
+    MCU_DATASHEET = 7
+    PROTEL_ALTIUM = 8
+    GENERAL_DATASHEET = 9
+    UNKNOWN = 10
+    USER_GUIDE = 11
+    REFERENCE_MANUAL = 12
+
+
+# PDF subtypes which require summary cheat sheets
+SummaryCheatSheetSubtypes: set[FileSubtypes] = {
+    FileSubtypes.USER_GUIDE,
+    FileSubtypes.REFERENCE_MANUAL
+}
+
+# PDF file subtypes that do not require docling text extraction or vectorization (example, schematic files)
+PDFNoVectorizeFileSubtypes: set[FileSubtypes] = {
+    FileSubtypes.SCHEMATIC
+}
+
+# File subtypes that have no schema to parse
+SchemalessFileSubtypes: set[FileSubtypes] = {
+    FileSubtypes.SCHEMATIC,
+    FileSubtypes.ERRATA,
+    FileSubtypes.MCU_DATASHEET,
+    FileSubtypes.USER_GUIDE,
+    FileSubtypes.REFERENCE_MANUAL
+}
+
+# File subtype names are for use with LLM, validating subtype response
+
+PDFFileSubtypeNames = Literal[
+    'SCHEMATIC',
+    'ERRATA',
+    'MCU_DATASHEET',
+    'GENERAL_DATASHEET',
+    'USER_GUIDE',
+    'REFERENCE_MANUAL',
+    'UNKNOWN'
+]
+
+OtherFileSubtypeNames = Literal[
+    'BOM',
+    'PADS_PCB_ASCII',
+    'KICAD_LEGACY_NET',
+    'KICAD_SPICE',
+    'PROTEL_ALTIUM'
+]
+
+PDFMimeTypes = {
+    "application/pdf",
+    "application/x-pdf",
+    "application/acrobat",
+    "applications/vnd.pdf",
+    "application/nappdf",
+}
+
+SupportedFileTypes = {
+    "CSV": {
+        "mime_types": {
+            "text/csv",
+            "text/plain"
+        },
+        "subtypes": {
+            "BOM"
+        }
+    },
+    "ASC": {
+        "mime_types": {
+            "text/plain"
+        },
+        "subtypes": {
+            "PADS_PCB_ASCII"
+        }
+    },
+    "NET": {
+        "mime_types": {
+            "text/plain"
+        },
+        "subtypes": {
+            "KICAD_LEGACY_NET",
+            "PROTEL_ALTIUM"
+        }
+    },
+    "CIR": {
+        "mime_types": {
+            "text/plain"
+        },
+        "subtypes": {
+            "KICAD_SPICE"
+        }
+    },
+    "PDF": {
+        "mime_types": PDFMimeTypes,
+        "subtypes": {
+            "SCHEMATIC",
+            "ERRATA",
+            "MCU_DATASHEET",
+            "REFERENCE_MANUAL"
+        }
+    }
+}
+
+# File subtype descriptions (for use in file subtype auto-discovery)
+
+# File subtypes for which we have parsers and do not the LLM to discover subtype
+KnownFileSubtypeDescriptions: Dict[SupportedFileTypes, Dict[str, str]] = {
+    "KICAD_LEGACY_NET": {
+        "name": 'KiCad Legacy Netlist',
+        "description": "Older KiCad netlist format containing components, nets, pins, and footprint references using plain text blocks like (comp ...), (net ...), and (pin ...); does not contain SPICE commands or PCB geometry."
+    },
+    "PROTEL_ALTIUM": {
+        "name": "Protel/Altium Designer Netlist",
+        "description": "Hierarchical bracketed netlist with components, footprints, and pin-to-net connections using sections like [Component] and [Net]; verbose structure unique to Altium/Protel; not a PCB layout or SPICE file."
+    }
+}
+
+# Only PDF files
+PDFSubtypeDescriptions: Dict[SupportedFileTypes, Dict[str, str]] = {
+    "SCHEMATIC": {
+        "name": "Schematic",
+        "description": "Diagrammatic circuit representation containing symbols, wires, net labels, sheet numbers, and component reference designators; typically PDF or image-based; not a table, netlist, PCB file, or simulation file."
+    },
+    "ERRATA": {
+        "name": "Engineering Errata File",
+        "description": "An ERRATA document lists known defects, mistakes, missing features, and silicon bugs in a released product. It is NOT a datasheet, does NOT describe product specifications, and consists of issue-by-issue bullet points with IDs, status, and workarounds. It never contains full electrical characteristics tables, application diagrams, or packaging information."
+    },
+    "MCU_DATASHEET": {
+        "name": "MCU Datasheet",
+        "description": "Microcontroller technical reference containing CPU architecture, memory maps, peripheral descriptions, electrical characteristics, pinouts, timing diagrams, and register information; exclusive to microcontrollers."
+    },
+    "GENERAL_DATASHEET": {
+        "name": "General Component Datasheet",
+        "description": "Datasheet for non-MCU components such as ICs, sensors, regulators, passives, and connectors, containing electrical specs, pin descriptions, operating conditions, and application circuits; no CPU or register-map content. A general component datasheet is a large, structured document containing electrical specifications, tables, operating ranges, application circuits, diagrams, pinouts, mechanical drawings, and packaging information. It is not a list of defects and does not describe known problems."
+    },
+    "USER_GUIDE": {
+        "name": "User Guide",
+        "description": "A practical, instructional document that explains how to use a hardware device, development board, evaluation kit, or module. A user guide focuses on setup, configuration, jumper settings, power requirements, interfaces, connectors, example usage, and safety notes. Unlike a datasheet, it avoids deep electrical specifications, register maps, or silicon details, and instead provides step-by-step procedures, diagrams, block overviews, and usage instructions intended for end users or developers."
+    },
+    "REFERENCE_MANUAL": {
+        "name": "Hardware Reference Manual",
+        "description": "A detailed, authoritative technical manual that defines the internal hardware architecture and low-level behavior of a device or system. It provides exhaustive functional descriptions of hardware blocks, registers, memory maps, address spaces, bit fields, timing relationships, and control logic. A hardware reference manual is used by firmware and driver developers for direct hardware interaction. It is not a datasheet, does not focus on electrical specifications or marketing summaries, and is not a step-by-step user guide."
+    },
+    "UNKNOWN": {
+        "name": "Unknown File",
+        "description": "File content does not match any known category such as BOM, PCB, netlist, schematic, datasheet, SPICE, or errata; used when insufficient or ambiguous information is present."
+    }
+}
+
+# Any other files subtypes
+OtherFileTypeDescriptions: Dict[SupportedFileTypes, Dict[str, str]] = {
+    "BOM": {
+        "name": "Bill of Materials (BOM)",
+        "description": "Tabular component list containing part numbers, quantities, manufacturers, and descriptions; typically CSV/XLSX rows and columns; does not contain nets, schematic symbols, PCB layout, or SPICE commands."
+    },
+    "PADS_PCB_ASCII": {
+        "name": "PADS ASCII PCB",
+        "description": "ASCII export of a PADS PCB layout containing footprints, padstacks, copper geometry, vias, XY coordinates, and board definitions; does not contain schematic symbols, part tables, or SPICE simulation directives."
+    },
+    "KICAD_SPICE": {
+        "name": "KiCad SPICE Netlist",
+        "description": "SPICE circuit simulation file containing directives (.tran, .ac, .dc, .include), models, and device lines (R, C, L, V, I elements); does not contain PCB footprints, tables, or datasheet content."
+    },
+    "UNKNOWN": {
+        "name": "Unknown File",
+        "description": "File content does not match any known category such as BOM, PCB, netlist, schematic, datasheet, SPICE, or errata; used when insufficient or ambiguous information is present."
+    }
+}

mfcli/constants/gemini.py

@@ -0,0 +1 @@
+MAX_GEMINI_PAGES = 1000

mfcli/constants/openai.py

@@ -0,0 +1,6 @@
+OPENAI_MAX_ENCODING_REQUEST_TOKENS = 250000
+OPENAI_ENCODING_MODEL = "cl100k_base"
+OPENAI_MAX_TOKENS_PER_CHUNK = 8192
+OPENAI_MAX_WINDOW_SIZE = 128 * 1024
+OPENAI_DEFAULT_EMBEDDING_MODEL = "text-embedding-3-large"
+OPENAI_DEFAULT_EMBEDDING_DIMENSIONS = 3072

mfcli/constants/pipeline_run_status.py

@@ -0,0 +1,3 @@
+PIPELINE_STATUS_IN_PROGRESS = 0
+PIPELINE_STATUS_COMPLETE = 1
+PIPELINE_STATUS_FAILURE = 2

mfcli/crud/file.py

@@ -0,0 +1,42 @@
+from mfcli.models.file import File
+from mfcli.models.file_metadata import FileMetadata
+from mfcli.models.pipeline_run import PipelineRun
+from mfcli.utils.logger import get_logger
+from mfcli.utils.orm import Session
+
+logger = get_logger(__name__)
+
+
+def create_file(db: Session, pipeline_run_id: int, metadata: FileMetadata) -> File:
+    logger.debug(f"Creating file: {metadata.name}")
+    existing_file: File | None = (
+        db.query(File)
+        .filter(File.md5 == metadata.md5)
+        .filter(File.pipeline_run_id == pipeline_run_id)
+        .one_or_none()
+    )
+    if existing_file:
+        raise ValueError(f"File {metadata.name} already exists and will not be processed")
+
+    pipeline_run: PipelineRun = (
+        db.query(PipelineRun)
+        .filter(PipelineRun.id == pipeline_run_id)
+        .one_or_none()
+    )
+    if not pipeline_run:
+        raise ValueError(f"Pipeline run ID does not exist: {pipeline_run_id}")
+
+    file = File(
+        name=metadata.name,
+        type=metadata.type_id,
+        mime_type=metadata.mime,
+        md5=metadata.md5,
+        path=str(metadata.path),
+        ext=metadata.ext,
+        is_datasheet=int(metadata.is_datasheet)
+    )
+    file.pipeline_run = pipeline_run
+    db.add(file)
+    db.flush()
+    logger.debug(f"File created: {file.id}")
+    return file

mfcli/crud/functional_blocks.py

@@ -0,0 +1,26 @@
+from typing import List
+
+from mfcli.models.functional_blocks import FunctionalBlockMeta, FunctionalBlock, FunctionalBlockComponent
+from mfcli.models.pipeline_run import PipelineRun
+from mfcli.utils.orm import Session
+
+
+def create_functional_blocks(
+    db: Session,
+    pipeline_run: PipelineRun,
+    blocks: List[FunctionalBlockMeta]
+) -> None:
+    db_blocks = []
+    for block in blocks:
+        db_block = FunctionalBlock(
+            name=block.name,
+            description=block.description,
+            pipeline_run=pipeline_run,
+            components=[]
+        )
+        for component_ref in (block.components or []):
+            db_block.components.append(
+                FunctionalBlockComponent(ref=component_ref)
+            )
+        db_blocks.append(db_block)
+    db.add_all(db_blocks)

mfcli/crud/netlist.py

@@ -0,0 +1,18 @@
+from mfcli.models.netlist import NetlistSchema, Netlist, NetlistComponent, NetlistPin
+
+
+def create_netlist(pipeline_run_id: int, netlist_schema: NetlistSchema) -> Netlist:
+    netlist = Netlist(pipeline_run_id=pipeline_run_id)
+    for component_schema in netlist_schema.components:
+        component = NetlistComponent(
+            ref_des=component_schema.ref_des,
+            part_number=component_schema.part_number
+        )
+        netlist.components.append(component)
+        for pin_schema in component_schema.pins:
+            pin = NetlistPin(
+                pin=pin_schema.pin,
+                net=pin_schema.net
+            )
+            component.pins.append(pin)
+    return netlist

mfcli/crud/pipeline_run.py

@@ -0,0 +1,17 @@
+from mfcli.models.pipeline_run import PipelineRun
+from mfcli.models.project import Project
+from mfcli.utils.logger import get_logger
+from mfcli.utils.orm import Session
+
+logger = get_logger(__name__)
+
+
+def create_pipeline_run(db: Session, project: Project) -> PipelineRun:
+    logger.debug("Creating pipeline run")
+    run = PipelineRun()
+    run.project = project
+    db.add(run)
+    db.flush()
+    logger.debug(f"Pipeline run created: {run.id}")
+    db.commit()
+    return run

mfcli/crud/project.py

@@ -0,0 +1,99 @@
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import List
+from uuid import uuid4
+
+from mfcli.utils.directory_manager import app_dirs
+from pydantic import ValidationError
+
+from mfcli.models.project import Project, project_name_regex
+from mfcli.models.project_metadata import ProjectConfig
+from mfcli.utils.logger import get_logger
+from mfcli.utils.migrations import run_migrations
+from mfcli.utils.orm import Session
+
+project_name_const = "Project name length must be between 3 and 45 and have any of these characters: [A-Za-z0-9_-]"
+
+logger = get_logger()
+
+
+def create_project(db: Session, repo_dir: str, name: str) -> Project:
+    logger.debug(f"Creating project with name: {name}")
+    name = name.strip()
+    if not re.match(project_name_regex, name):
+        raise ValueError(project_name_const)
+    existing_project = db.query(Project).filter(Project.name == name).one_or_none()
+    if existing_project:
+        raise ValueError("A project with this name already exists")
+    project = Project(
+        name=name,
+        repo_dir=str(Path(repo_dir)),
+        index_id=uuid4().hex
+    )
+    db.add(project)
+    db.flush()
+    logger.debug(f"Project created: {project}")
+    return project
+
+
+def get_project_by_name(db: Session, name: str) -> Project:
+    project: Project | None = (
+        db.query(Project)
+        .filter(Project.name == name)
+        .one_or_none()
+    )
+    if not project:
+        raise ValueError(f"A project by this name does not exist: {name}")
+    return project
+
+
+def _list_projects(db: Session) -> List[Project]:
+    return db.query(Project).all()
+
+
+def read_project_config_file() -> ProjectConfig:
+    file_path = app_dirs.config_file_path
+    logger.debug(f"Reading metadata file: {file_path}")
+    if not os.path.exists(file_path):
+        print('Could not find metadata file. Are you in the correct directory? Or if this is a new project, please initialize this repo with "mfcli init"')
+        sys.exit(1)
+    if not os.access(file_path, os.R_OK):
+        print(f"Could not access repo file: {file_path}")
+        sys.exit(1)
+    with open(file_path, "r") as f:
+        try:
+            return ProjectConfig(**json.loads(f.read()))
+        except ValidationError as e:
+            logger.error(f"Metadata file is corrupted: {file_path}")
+            raise e
+
+
+def init_project(project_name: str | None, repo_dir: Path | None = None):
+    try:
+        with Session() as db:
+            run_migrations()
+            if not repo_dir:
+                repo_dir = Path(os.getcwd())
+            logger.debug(f"Initializing project for repo dir: {repo_dir}")
+            file_path = app_dirs.config_file_path
+            if os.path.exists(file_path):
+                project_config = read_project_config_file()
+                get_project_by_name(db, project_config.name)
+                logger.debug(f"Project has already been initialized: {project_config.name}")
+                return
+
+            repo_dir = str(repo_dir)
+            if not project_name:
+                project_name = input("Please choose a project name [A-Za-z0-9_-]: ")
+            create_project(db, repo_dir, project_name)
+            project_config = ProjectConfig(name=project_name)
+            logger.debug(f"Creating metadata file: {file_path}")
+            with open(file_path, "w") as f:
+                f.write(json.dumps(project_config.model_dump(), indent=2))
+            db.commit()
+    except Exception as e:
+        logger.exception(e)
+        logger.error("Error initializing project")

mfcli/digikey/digikey.py

@@ -0,0 +1,105 @@
+import time
+
+import requests
+from requests import HTTPError
+
+from mfcli.utils.config import get_config
+from mfcli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+class DigiKey:
+    def __init__(self):
+        self._config = get_config()
+        self._url = "https://api.digikey.com"
+        self._token: str | None = None
+        self._get_access_token()
+        self._session = requests.Session()
+        headers = {
+            "Authorization": f"Bearer {self._token}",
+            "X-DIGIKEY-Client-Id": self._config.digikey_client_id,
+            "Content-Type": "application/json",
+            "Accept": "application/json"
+        }
+        self._session.headers = headers
+
+    @staticmethod
+    def _format_datasheet_url(url: str | None) -> str | None:
+        if url and url.startswith('//'):
+            return f"https:{url}"
+        return url
+
+    def _api_call(self, method: str, url: str, data: dict | None = None) -> dict:
+        max_retries = 5
+        timeout = 5
+        backoff_factor = 2
+
+        for attempt in range(1, max_retries + 1):
+            try:
+                resp = self._session.request(method=method, url=url, json=data, timeout=timeout)
+
+                if resp.status_code == 429:
+                    if attempt == max_retries:
+                        resp.raise_for_status()
+
+                    retry_after = resp.headers.get("Retry-After")
+                    delay = float(retry_after) if retry_after is not None else backoff_factor * (2 ** (attempt - 1))
+                    time.sleep(delay)
+                    continue
+
+                resp.raise_for_status()
+                return resp.json()
+
+            except requests.exceptions.Timeout:
+                # Handle timeout — retry with exponential backoff
+                if attempt == max_retries:
+                    raise  # give up after last attempt
+                delay = backoff_factor * (2 ** (attempt - 1))
+                time.sleep(delay)
+                continue
+
+        raise RuntimeError("Exhausted retries without success.")
+
+    def _get_access_token(self):
+        logger.debug("Fetching Digi-Key access token")
+        headers = {"Content-Type": "application/x-www-form-urlencoded"}
+        data = {
+            "client_id": self._config.digikey_client_id,
+            "client_secret": self._config.digikey_client_secret,
+            "grant_type": "client_credentials"
+        }
+        url = f"{self._url}/v1/oauth2/token"
+        resp = requests.post(url, headers=headers, data=data)
+        token_data = resp.json()
+        self._token = token_data["access_token"]
+
+    def _datasheet_from_part_number(self, part_number: str) -> str | None:
+        url = f"{self._url}/products/v4/search/{part_number}/productdetails"
+        resp = self._api_call('GET', url)
+        if not resp.get("Product"):
+            return None
+        return resp["Product"].get("DatasheetUrl")
+
+    def _keyword_search(self, part_number: str) -> str | None:
+        payload = {
+            "Keywords": part_number,
+            "RecordCount": 1
+        }
+        url = f"{self._url}/products/v4/search/keyword"
+        resp = self._api_call('POST', url, payload)
+        if not resp.get("ExactMatches"):
+            return None
+        return resp["ExactMatches"][0].get("DatasheetUrl")
+
+    def datasheet(self, part_number: str) -> str | None:
+        datasheet_url = None
+        try:
+            datasheet_url = self._datasheet_from_part_number(part_number)
+        except HTTPError as e:
+            # Handle 404 with keyword search API, otherwise raise HTTP error
+            if not e.response.status_code == 404:
+                raise e
+        if not datasheet_url:
+            datasheet_url = self._keyword_search(part_number)
+        return self._format_datasheet_url(datasheet_url)

mfcli/main.py

@@ -0,0 +1,5 @@
+from mfcli.cli.main import run_cli
+
+
+def main():
+    run_cli()

mfcli/mcp/configs/cline_mcp_settings.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "mfcli-mcp": {
+      "disabled": false,
+      "timeout": 60,
+      "type": "stdio",
+      "command": "python",
+      "args": ["-m", "mfcli.mcp.server"]
+    }
+  }
+}

mfcli/mcp/configs/mfcli.mcp.json

@@ -0,0 +1,7 @@
+{
+  "mcp_server": {
+    "name": "MFCLI MCP Server",
+    "command": "python",
+    "args": ["-m", "mfcli.mcp.server"]
+  }
+}

mfcli/mcp/mcp_instance.py

@@ -0,0 +1,6 @@
+from fastmcp import FastMCP
+
+# Create the MCP instance that will be shared across modules
+mcp = FastMCP(
+    name="ChromaDB Engineering Docs"
+)

mfcli/mcp/server.py

@@ -0,0 +1,37 @@
+import sys
+
+import chromadb
+from chromadb.utils import embedding_functions
+
+from mfcli.mcp.mcp_instance import mcp
+from mfcli.utils.config import get_config
+from mfcli.utils.directory_manager import app_dirs
+
+# Import tools to register them with mcp
+import mfcli.mcp.tools.query_knowledgebase
+
+
+def chroma_db_connection_test():
+    try:
+        config = get_config()
+        test_chroma_client = chromadb.PersistentClient(path=app_dirs.chroma_db_dir)
+        test_openai_ef = embedding_functions.OpenAIEmbeddingFunction(
+            api_key=config.openai_api_key,
+            model_name=config.embedding_model
+        )
+        test_chroma_client.get_or_create_collection("engineering_docs", embedding_function=test_openai_ef)
+        print(f"✓ Connected to ChromaDB at: {app_dirs.chroma_db_dir}", file=sys.stderr, flush=True)
+        print(f"✓ Collection: engineering_docs", file=sys.stderr, flush=True)
+    except Exception as e:
+        print(f"✗ Failed to connect to ChromaDB: {e}", file=sys.stderr, flush=True)
+        raise
+
+
+def main():
+    """Entry point for mfcli-mcp command."""
+    chroma_db_connection_test()
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mfcli/mcp/state_manager.py

@@ -0,0 +1,51 @@
+"""State manager for MCP server to persist state between calls."""
+import json
+from pathlib import Path
+from typing import Optional
+
+from mfcli.utils.directory_manager import app_dirs
+
+
+class MCPStateManager:
+    """Manages persistent state for the MCP server."""
+    
+    def __init__(self):
+        state_dir = Path(app_dirs.app_data_dir)
+        try:
+            state_dir.mkdir(parents=True, exist_ok=True)
+        except Exception:
+            # If we can't create the directory, we'll operate with in-memory state only.
+            pass
+        self.state_file = state_dir / "mcp_state.json"
+        self._state = self._load_state()
+    
+    def _load_state(self) -> dict:
+        """Load state from disk."""
+        if self.state_file.exists():
+            try:
+                with open(self.state_file, 'r') as f:
+                    return json.load(f)
+            except Exception:
+                return {}
+        return {}
+    
+    def _save_state(self):
+        """Save state to disk."""
+        try:
+            with open(self.state_file, 'w') as f:
+                json.dump(self._state, f, indent=2)
+        except Exception:
+            pass  # Silently fail if we can't save state
+    
+    def get_last_project_name(self) -> Optional[str]:
+        """Get the last used project name."""
+        return self._state.get('last_project_name')
+    
+    def set_last_project_name(self, project_name: str):
+        """Set the last used project name."""
+        self._state['last_project_name'] = project_name
+        self._save_state()
+
+
+# Singleton instance
+state_manager = MCPStateManager()