🚀 Notioneer

Notioneer is a Python toolkit that automates the flow of structured data between LLMs and Notion. It lets you generate, validate, and insert entries (like tasks, projects, goals) into Notion databases using JSON dumps produced by an LLM, all while ensuring schema compliance and relation resolution. The project was developed for personal use but is open-sourced for anyone interested in similar workflows. Use at your own risk.

---

✨ Features

• 🔄 Schema-driven validation – every entry conforms to Notion’s database schema.
• 🧩 Relation handling with temp_id – create interlinked tasks and projects without knowing page IDs.
• 📦 Database export & schema generation – automatically pull schemas and entries from Notion.
• ✍️ Instruction merging – build LLM-ready instructions with embedded schema contracts.
• ⚡ Block operations – append, insert, replace, update, or delete Notion blocks on the fly.

With Notioneer, you can design workflows where an LLM generates structured actions, and they’re safely executed in Notion without breaking consistency.

---

📦 Installation

Clone the repository and install dependencies:

git clone https://github.com/YOUR_USERNAME/notioneer.git
cd notioneer
pip install .

---

⚙️ Configuration

There are three global variables that you can set:

• CONFIG_PATH (default: config.json) – path to your config file.
• SCHEMA_DIR (default: schemas/) – directory to store generated schema
• EXPORT_DIR (default: exports/) – directory to store exported entries

There are two ways to set up configuration via config.json:

1. Provide your token and a first database Example config.json:

    {
        "notion_token": "secret_123",
        "databases": {
            "tasks": {
                "database_id": "abcd-1234-efgh-5678",
                "schema": "tasks_schema.json",
                "output": "exported_tasks.json",
                "filter": {                             // optional
                    "property": "Status",
                    "status": {
                        "does_not_equal": "Done"
                    }
                },
                "required": [],                         // optional
                "icon": {                               // optional
                    "type": "external",
                    "external": {
                        "url": "https://www.notion.so/icons/checkmark_orange.svg"
                    }
                }
            }
        }
    }

   In the field filter you can specify a filter according to Notion's API. See the docs for details.

   In the field required you can specify a list of properties that must be present in the database entries. This is useful to ensure that certain fields are always filled when creating or updating entries.

2. Provide just your integration token Then, bootstrap schemas by providing a database ID directly when calling the schema generator:

   Example config.json:

   {
     "notion_token": "secret_123"
   }

   Example command:

   python scripts/generate_schemas.py <DATABASE_ID>

👉 In both cases, notion_token must be your Notion integration token. See Notion’s API docs for how to create one.

---

🚀 Usage

To get started, follow this setup flow:

1. Generate schemas

This step fetches schema definitions for your database(s). If only a token is provided in config.json, you must supply a database ID. Otherwise, you can supply database names to restrict which schemas to generate:

python scripts/generate_schemas.py <DATABASE_ID> OR [database_name ...]

The database ID can be found in the URL of your Notion database or via the Notion API. E.g., https://www.notion.so/<DATABASE_ID>?v=....

---

2. Merge instructions

The base instructions are in docs/base_instructions.md. They contain general rules for the LLM to follow. In order to ensure the LLM knows the exact schema of your Notion databases, you need to merge these with the generated schema definitions. You can specify which schemas to include by passing their safe names as arguments:

python scripts/generate_instructions.py [database_name ...]

This produces instructions.md, which contains both the general rules and the specific schemas.

---

3. Use with an LLM

There are two main workflows:

A. Let the LLM create new entries directly

• Provide the instructions.md file to the LLM.

• Ask it to generate a dump.json containing new entries (tasks, projects, etc.).

• Apply the entries into Notion. The script will by default expect dump.json in the current directory, but you can specify a different path:

  python scripts/dump_entries.py <DUMP_FILE_PATH>

B. Give the LLM context from existing data

• First, export existing entries. The script will by default export all known databases, but you can specify which ones to export by passing their safe names as arguments:

  python scripts/fetch_entries.py [database_name ...]

• Provide both instructions.md and the exported JSON (e.g., exported_tasks.json) to the LLM.

• The LLM can then generate updates (with page_id) or new entries that reference existing items.

• Apply the updates/new entries:

  python scripts/dump_entries.py <DUMP_FILE_PATH>

This makes it possible to:

• Start fresh with new entries, or
• Work incrementally by providing the LLM with current data and asking for modifications or extensions.

Warnings

Notioneer does currently support deletions only for content blocks within a page. If you want to remove entries, you must do so manually in Notion.

Also, database exports from the fetch_entries script can become large (i.e., 100k+ lines of JSON) if your databases contain many entries. Be mindful of token limits when providing this data to an LLM and the context window size.

Suggestions

The base instructions can be customized to fit your specific use case. You might want to:

• Add more examples of desired entries.
• Specify particular workflows or rules for how entries should be created or linked.
• Tailor the language model’s behavior to better suit your needs.

---

📂 Project Structure

Notioneer/
├── notioneer/                    # Core package
│   ├── __init__.py
│   ├── api.py
│   ├── operations.py
│   ├── schema_utils.py
│   ├── schemas.py
│   └── generate_schemas.py
│
├── scripts/                      # CLI entry points
│   ├── dump_entries.py
│   ├── fetch_entries.py
│   ├── generate_schemas.py
│   └── generate_instructions.py
│
├── docs/
│   └── base_instructions.md
│
├── config.json                   # Example config (dummy values only)
├── requirements.txt
├── setup.py
├── README.md
├── LICENSE
├── .gitignore
└── .gitattributes

---

🧪 Example Workflow

1. Generate schemas from your Notion DB

   python scripts/generate_schemas.py projects tasks

2. Merge instructions for your LLM

   python scripts/generate_instructions.py

3. Use the instructions (and optionally exported data) with your LLM to produce a dump.json.

4. Insert or update those entries in Notion:

   python scripts/dump_entries.py dump.json

5. Verify results by exporting again:

   python scripts/fetch_entries.py projects tasks

---

📜 License

MIT License — see LICENSE.

---

🤝 Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you’d like to change.

---

🔗 Links

• Notion API Reference
• Notion Python SDK (alternative library)

---