Galmuri

English · 한국어

Connect document sources, prepare searchable documents, and serve them to RAG applications through MCP, HTTP, gRPC, or CLI.

Start with a local folder and the generated sample app. Replace parsing, document transformations, embeddings, or vector storage as needed. Your RAG application uses the document and search APIs to build answers.

Status: development preview. Install and import galmuri; the command is galmuri or python -m galmuri. Source access is provided by the independent duru library.

Contents

• Use cases
• Quick start
• Your generated project
• Customize processing
• Agent skill
• Sources, models, and storage
• Accounts and document access
• Serve your app
• Commands and recovery
• Current limits
• Development

Use cases

Included parsers handle text, Markdown, and Python source. Local multilingual embeddings and SQLite vectors work with the default sample.

Quick start

Requires Python 3.12+. Linux is the deployment target; the Dockerfile uses Python 3.13. Install from local checkouts arranged as follows:

workspace/
├── access/     # duru checkout
└── project/    # framework checkout

From workspace/:

cd project
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ../access -e '.[mcp,grpc]'

python -m galmuri new ./example
cd example
python manage.py sync
python manage.py call search --app sample --mode lexical --query welcome
python manage.py serve http

The sample includes welcome.md and clinic.md. Sync publishes their documents; the search command returns matching document data. Browse them at http://127.0.0.1:8000/dashboard. Stop the server with Ctrl+C.

The first embedding operation downloads model weights. Set EMBEDDING_CACHE before sync to reuse a populated cache or keep it in a persistent location. The default local model needs no LLM API key.

To try semantic search from the generated project:

python manage.py call search --app sample --mode vector --query "Where should I go when I feel unwell?"

Your generated project

The default App connects a source without a custom read or parser function:

# apps/sample/app.py
from galmuri import App
from .source.local import source

sample = App(name="sample", source=source)

To use another folder, change the ReadOnlyLocalProvider path in apps/sample/source/local.py. The sample is read-only; client updates require a source with conditional-write support.

Choose a preset when creating a new directory:

Presets are mutually exclusive. The lexical and Qdrant tutorials use trusted host identities rather than the default account-enabled setup.

Customize processing

From the framework checkout, generate the runnable processing example:

python -m galmuri new ./custom-example --process

It adds these files to the sample app:

apps/sample/
├── app.py
├── process.py
└── views/
    ├── __init__.py
    ├── normalization.py
    └── metadata.py

Edit views/normalization.py to change document text:

from dataclasses import replace

def normalize(documents):
    return tuple(
        replace(document, text=document.text.strip() + "\n")
        for document in documents
    )

In process.py, connect the function and the supplied metadata function:

from galmuri import Pipeline, Step
from .views.normalization import normalize
from .views.metadata import label

process = (
    Pipeline.default()
    .then(Step("normalize", process=normalize))
    .then(Step("label", process=label))
)

The generated app.py selects it with App(name="sample", source=source, process=process). Functions run when processing work executes. Add .then(Step(...)) for another step, or change declaration order to change the sequence.

These added steps receive and return document tuples. Default parsing runs first; document permission preparation follows your transformations. For a fully custom sequence, use Pipeline(*steps) with explicit file, documents, and terminal result boundaries. A plain App(process=my_function) accepts File and returns IngestResult.

Configure only the parts you need:

Config classes above are imported from framework, except SyncPolicy, which is in galmuri.collection.policies. For example, SyncPolicy(mode="scan", interval=86400) schedules a daily full scan. Omitted settings retain defaults.

Agent skill

The repository includes using-galmuri, an agent skill for creating apps, changing processing steps and checking document access. From this checkout, install it for Codex with:

mkdir -p "${CODEX_HOME:-$HOME/.codex}/skills"
cp -R skills/using-galmuri "${CODEX_HOME:-$HOME/.codex}/skills/"

Restart or reload skill discovery, then ask the agent to use $using-galmuri. Other compatible agents can install the same skill folder. Wheels also include it under share/galmuri/skills/using-galmuri in the Python installation's data directory.

Sources, models, and storage

Supply credentials and account/folder/channel IDs to the resource library. A provider with root_uri can be passed directly as App.source; otherwise use galmuri.sources.resources.Resources(provider, root_uri). Google-native documents require an explicit export format. Slack messages arrive as JSON resources; customize parsing to select the fields you need.

The current provider bridge scans snapshots and compares versions. It does not automatically subscribe to native Google Drive or Slack incremental feeds.

An App can set retrieval=RetrievalConfig(embedding=my_embedding, store=my_store, mode="hybrid"). Missing embedding/store providers are filled from defaults. The default vector store follows the App's selected database. EmbeddingConfig(process=..., query_process=..., spec=...) connects paired document-batch and query functions. Existing EmbeddingProvider, Chunker, and VectorStore implementations can also be passed directly.

Set retrieval=None to disable vector indexing. Selecting lexical as the default search mode alone does not disable vector builds. For PostgreSQL aliases/namespaces, Qdrant setup, and provider configuration, see the configuration and operations reference.

Accounts and document access

From a default or --process generated project:

python manage.py createsuperuser root
python manage.py serve http

The first command prompts for a password. Sign in at http://127.0.0.1:8000/dashboard to manage accounts, groups, document permissions, and personal MCP tokens. There is no default account or password.

Omitted grants inherit DEFAULT_PERMISSIONS in config/settings.py. Generated defaults allow reads and writes; explicit empty grants deny access. Source write support is still required, so the read-only sample exposes no write tool.

Group membership changes apply without reindexing. Ordinary administrators manage permissions; root can also bypass document ACLs. Token scopes, app restrictions, source capabilities, and version checks still apply to root.

For a read-only account token:

python manage.py createuser reader
python manage.py mcp-token reader --scope read --app sample --token-file .runtime/reader.token
FRAMEWORK_TOKEN_FILE=.runtime/reader.token python manage.py serve mcp

Local account commands require trusted OS access to the project. Restricted documents require verified credentials; tool arguments cannot assert a user/group. Invalid, expired, or revoked credentials are rejected.

Serve your app

Run from the generated project:

serve normally starts the scheduler and one local worker. Use --workers 0 when running workers separately. The MCP adapter is a stdio server. HTTP deployment needs a public HTTPS origin and TLS proxy; generated loopback HTTP settings are for local use.

Build the supplied image from the framework checkout, with the sibling access/ checkout present:

docker build --build-context duru=../access -t galmuri-local .
docker run --rm galmuri-local --help

Mount a generated project at /workspace to retain its code and state.

Commands and recovery

Run from a generated project. Replace BUILD_ID with a build ID from index status. For management calls such as status, first create a root session after creating your root account: python manage.py login root --token-file .runtime/operator.token. It prompts for the password.

Standard Runtime workers persist accepted step outputs and resume after them. HTTP remote workers and custom workflows retry the whole process. Callbacks interrupted before their output is saved may run again: make external side effects idempotent.

Document publication and vector publication finish separately. Check index-status after sync; a drain can leave future retries or failed jobs. Change an implementation's revision when changing its behavior in place, then activate. State from older parser bindings may also require activate. See the reference for detailed recovery and store-cleanup commands.

Current limits

• Pipelines support linear steps; branches, loops, and DAG scheduling are not included.
• Google Drive/Slack providers currently support read/stat/list. Their account APIs are tested with local HTTP fixtures; live-account verification is separate.
• PDF/OCR parsers and OpenSearch require additional implementations.
• SQLite is for a single host. Use PostgreSQL to share metadata/account state across hosts, with compatible code and source settings in every process.
• SQLite/PostgreSQL vector stores use exact cosine search. Large-corpus throughput, ANN quality, and long-running production operation need separate evaluation.

Development

From the framework checkout:

python -m pip install -e ../access -e '.[mcp,grpc,postgres,dev]'
python -m pytest -q
python -m ruff check src tests tools
python -m ruff format --check src tests tools
python -m build --wheel

Set FRAMEWORK_POSTGRES_DSN to a disposable PostgreSQL instance for remote DB tests. Optional live-model/LLM checks are separate from the ordinary suite; commands are in the reference.

Include a reproducible example and relevant checks with fixes or extensions. Keep the English and Korean READMEs aligned for user-facing changes.

See contributing, security reporting, changes and the release procedure.

License

Distributed under the BSD 3-Clause license.