AgenticDomiKnowS (ADS)

Code for the paper An Agentic Framework for Neuro-Symbolic Programming, published in the Proceedings of the 20th Conference on Neurosymbolic Learning and Reasoning (NeSy 2026, PMLR).

AgenticDomiKnowS (ADS) translates free-form natural language task descriptions into complete, executable DomiKnowS programs. Neuro-symbolic frameworks such as DomiKnowS integrate symbolic constraints into deep learning models, which can make them more robust, interpretable, and data-efficient, but authoring these programs requires expertise in the library's declarative syntax. ADS removes this barrier with an agentic workflow that generates, executes, and refines each component of the program separately: retrieval-augmented examples ground the generation of the conceptual graph and its logical constraints, while reviewer and execution agents iteratively repair semantic and syntactic errors. An interactive interface supports optional human-in-the-loop refinement of intermediate outputs and exports the final program as a plug-and-play Jupyter notebook.

In our user study, ADS enabled both DomiKnowS experts and non-users to construct complete neuro-symbolic programs in 10 to 15 minutes, whereas manually authoring even a single component of such a program takes about an hour. A hosted instance of the interface is available at hlr-demo.egr.msu.edu.

Repository Structure

• Agent/: LLM agents for conceptual graph generation, review, execution validation, and sensor code generation
• server/: FastAPI backend orchestrating the agentic workflow
• frontend/agentic-domiknows/: Next.js human-in-the-loop interface
• domiknows/: DomiKnowS library code and example datasets
• Examples/: DomiKnowS programs used as the retrieval corpus for the RAG component

Running Locally

Requirements: Python 3.13, Node.js >= 18, Docker (for MongoDB), Graphviz, and an OpenAI API key.

1. Start MongoDB, which stores users, tokens, request logs, and graph-state snapshots:

   docker run --name mongodb -p 27017:27017 -d mongodb/mongodb-community-server:latest

2. Create a .env file at the repository root:

   OPENAI_API_KEY=<your openai key>
   # optional, only needed for offline model experiments
   DEEPSEEK_API_KEY=<your deepseek key>
   MOONSHOT_API_KEY=<your moonshot key>
   

3. Install Python dependencies and start the backend, served at http://localhost:8001:

   pip install -r requirements.txt
   cd server && python main.py

4. Install frontend dependencies and start the interface, served at http://localhost:49790:

   cd frontend/agentic-domiknows
   npm install && npm run dev

5. Register a user (registration is restricted to localhost):

   curl -X POST http://localhost:8001/auth/register \
     -H "Content-Type: application/json" \
     -d '{"username": "name", "password": "password"}'

Open http://localhost:49790, enter a task description, review and optionally refine the generated conceptual graph, then proceed through the sensor workflow to download the final program as a Jupyter notebook.

The details of the workflow design and its evaluation are described in the paper.

Citation

If you use ADS in your research, please cite:

@inproceedings{nafar2026agentic,
  title     = {An Agentic Framework for Neuro-Symbolic Programming},
  author    = {Nafar, Aliakbar and Chigurupati, Chetan and Kamali, Danial and Karimian, Hamid and Kordjamshidi, Parisa},
  booktitle = {Proceedings of the 20th Conference on Neurosymbolic Learning and Reasoning (NeSy)},
  year      = {2026},
  volume    = {284},
  publisher = {PMLR}
}

License

This project is released under the MIT License.

Acknowledgments

This project is partially supported by the Office of Naval Research (ONR) grant N00014-23-1-2417.