What Is the Purpose of `pyproject.toml` in Semantica? A Deep Dive into the Build Configuration

The pyproject.toml file in the Semantica repository serves as the central configuration file that defines how the library is built, packaged, and distributed, following PEP 517/518 standards to specify build backends, metadata, dependencies, and CLI entry points.

The semantica-agi/semantica repository uses pyproject.toml as its single source of truth for project configuration, replacing legacy setup.py files with a modern, declarative standard. This approach enables reproducible builds across diverse environments while supporting the library's modular architecture. Understanding this file is essential for contributors and users who need to install specific components of this semantic AI framework.

Build System and Backend Configuration

The [build-system] section at the beginning of pyproject.toml (lines 1–4) declares the build backend required to generate installable wheels. Semantica uses setuptools and wheel as its build backend, ensuring compatibility with standard Python packaging tools.

[build-system]
requires = ["setuptools", "wheel"]
build-backend = "setuptools.build_meta"

This configuration complies with PEP 517 and PEP 518, allowing pip to automatically install the build dependencies before attempting to build the package from source.

Project Metadata and Core Dependencies

The [project] section (lines 5–20) contains essential package metadata including the name, version, description, license, authors, and supported Python versions. This declarative approach eliminates the need for executable code during metadata extraction.

Core runtime dependencies are specified in [project.dependencies] (lines 48–95), which lists packages required for basic functionality:

• numpy and pandas for data manipulation
• rdflib and networkx for graph operations
• requests for HTTP communication

These dependencies install automatically with pip install semantica, providing the foundation for knowledge base operations without optional backends.

Modular Installation with Optional Dependencies

Semantica's architecture supports multiple LLM providers, graph databases, and vector stores through optional dependencies defined in [project.optional-dependencies] (lines 107–334). This design allows users to install only the components they need, reducing environment bloat and dependency conflicts.

Key extras include:

• llm-openai — Support for OpenAI's GPT models
• graph-neo4j — Neo4j graph database connector
• vectorstore-faiss — Facebook AI Similarity Search integration
• dev — Development tools including pytest, mypy, and black

Users can combine extras using comma-separated syntax to customize their installation precisely.

CLI Entry Points and Console Scripts

The [project.scripts] section (lines 37–44) registers command-line entry points that map to functions within the codebase. After installation, these commands are available globally in the user's environment:

• semantica — Main CLI interface
• semantica-server — Server deployment command
• semantica-worker — Background worker process

These entry points resolve to implementations in semantica/cli.py, enabling direct execution without manual Python invocation.

Development Tool Configuration

The pyproject.toml file also centralizes configuration for development tooling in [tool.*] sections (lines 55–66), ensuring consistent formatting and testing across the codebase:

[tool.black]
line-length = 88
target-version = ["py310"]

[tool.isort]
profile = "black"

[tool.pytest.ini_options]
testpaths = ["tests"]

Additionally, [tool.setuptools] (lines 46–53) directs the build system on which packages and data files to include, ensuring static assets and ontology files ship with the wheel.

Installing Semantica with Specific Dependencies

The pyproject.toml configuration enables fine-grained installation strategies. Use these commands to install different configurations of the library:

# Install core library only

pip install semantica

# Install with OpenAI LLM support

pip install "semantica[llm-openai]"

# Install with multiple backends (Neo4j graph + Qdrant vector store)

pip install "semantica[graph-neo4j,vectorstore-qdrant]"

# Install development dependencies for contributing

pip install "semantica[dev]"

After installation, verify the CLI entry points work correctly:

semantica --help
semantica-server --port 8000

You can then import the package and initialize specific backends that correspond to your installed extras:

from semantica import Graph, KnowledgeBase

# Requires graph-neo4j extra installed

g = Graph.from_neo4j(uri="bolt://localhost:7687", auth=("user", "pass"))
kb = KnowledgeBase(graph=g)

kb.add_triple(subject="Alice", predicate="knows", object="Bob")

Summary

• pyproject.toml serves as the single source of truth for building, packaging, and distributing Semantica according to modern Python standards.
• Build system configuration uses setuptools and wheel (lines 1–4) to generate installable artifacts.
• Modular dependency management via optional extras (lines 107–334) allows selective installation of LLM providers, graph backends, and vector stores.
• CLI entry points (lines 37–44) expose semantica, semantica-server, and semantica-worker commands globally after installation.
• Development tooling integration (lines 55–66) ensures consistent code formatting, import sorting, and test execution across the project.

Frequently Asked Questions

What build backend does Semantica use?

Semantica uses setuptools as its build backend, declared in the [build-system] section (lines 1–4) of pyproject.toml. This choice ensures broad compatibility with existing Python packaging infrastructure while supporting modern PEP 517 build isolation.

How do I install only specific extras like Neo4j or OpenAI support?

Append the extra name in square brackets to the package name: pip install "semantica[graph-neo4j]" for Neo4j support or pip install "semantica[llm-openai]" for OpenAI integration. You can combine multiple extras with commas: pip install "semantica[llm-openai,graph-neo4j]".

What CLI commands are available after installing Semantica?

The [project.scripts] section registers three primary commands: semantica for the main interface, semantica-server for launching the server component, and semantica-worker for background processing. These map to functions in semantica/cli.py and are available immediately after installation.

Where is the package metadata such as version and license defined?

Package metadata including name, version, description, license, and authors is defined declaratively in the [project] section (lines 5–20) of pyproject.toml. This eliminates the need to execute Python code to extract metadata, speeding up dependency resolution and enabling static analysis tools.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}