Metadata-Version: 2.4
Name: narad
Version: 0.1.1
Summary: A lightweight personal CRM for the command line and local browser.
Author-email: Gaurav Gat <gauravvgat@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.12
Requires-Dist: fastapi>=0.135.3
Requires-Dist: jinja2>=3.1.6
Requires-Dist: python-multipart>=0.0.24
Requires-Dist: rich>=14.3.3
Requires-Dist: typer>=0.24.1
Requires-Dist: uvicorn>=0.44.0
Description-Content-Type: text/markdown

# Narad

Narad is a lightweight, local-first personal CRM for people who want a fast way
to remember contacts, conversations, and follow-ups without adopting a sales
platform.

It gives you a Python CLI, a compact local browser UI, and a SQLite database on
your machine. Use it to track people, organizations, relationship notes,
follow-up tasks, contact sources, interaction channels, tags, and full-text
search.

## Why Narad?

Most CRMs are built for teams, pipelines, dashboards, and reporting. Narad is
for a single user (including local agents) who wants to keep context:

- Consultants tracking client outreach and follow-ups
- Sales reps managing relationships in a lightweight flow
- Solo founders organizing contacts and partnerships

- Who did I meet?
- Where did this relationship come from?
- What did we talk about last time?
- What should I follow up on today?
- Can I find that note from LinkedIn, WhatsApp, a call, or a conference?

Narad keeps that loop small, searchable, and local.

## Features

- Contacts with name, email, phone, title, location, source, company, and tags.
- Organizations linked to contacts.
- Relationship notes and interactions with optional channel metadata.
- Follow-up tasks with due dates and completion state.
- `today` view for overdue tasks, tasks due today, and recent notes.
- FTS5 search across contacts, organizations, notes, tasks, sources, channels,
  and tags.
- Local browser UI served by FastAPI at `http://127.0.0.1:8765`.
- Plain SQLite storage under your own home directory.

Contact `source` means where the relationship originated, such as `linkedin`,
`tea shop`, `twitter`, `referral`, or `conference`.

Interaction `channel` means where a specific note or event happened, such as
`call`, `email`, `whatsapp`, `linkedin`, `twitter`, or `in-person`.

## Quick Start

Narad requires Python 3.12 or newer.

Install the published package from PyPI:

```sh
uv tool install narad==0.1.0
```

PyPI release: [narad 0.1.0](https://pypi.org/project/narad/0.1.0/)

Then initialize your local database:

```sh
narad init
narad today
```

To install from a checkout instead:

```sh
git clone https://github.com/gauravvgat/narad.git
cd narad
uv tool install .
```

For contributor-style local development, use `uv sync` and run commands with
`uv run narad ...` instead.

## Usage

Create a small relationship graph:

```sh
narad add org "Acme Labs" --website https://acme.example --tag investor
narad add contact "Asha Rao" --company "Acme Labs" --email asha@example.com --source linkedin --tag warm
narad add note "Discussed pilot timeline" --contact "Asha" --channel whatsapp
narad add task "Send pilot proposal" --due today --contact "Asha"
```

Keep it current:

```sh
narad edit contact 1 --email asha@acme.example --source conference
narad list contacts --tag warm
narad list tasks --status open
narad search "pilot"
narad show 1
narad done 1
```

Open the local web UI:

```sh
narad serve
```

Useful commands:

- `narad init`: create the Narad home directory and initialize the database.
- `narad today`: show overdue tasks, tasks due today, and recent notes.
- `narad list contacts`: list contacts, optionally filtered by tag.
- `narad list tasks`: list tasks by `open`, `done`, or `all`.
- `narad search`: search across your CRM.
- `narad show`: show one contact profile with tasks and timeline.
- `narad serve`: start the local browser UI.
- `narad path`: print the configured home and database paths.
- `narad search-reindex`: rebuild the full-text search index.

## Storage And Privacy

By default, Narad stores data in:

```text
~/.narad/narad.db
```

For isolated runs, demos, tests, or agent sandboxes, override the paths:

```sh
export NARAD_HOME=/tmp/narad-home
export NARAD_DB=/tmp/narad-home/narad.db
```

Narad is local-first and single-user in v1. The web UI binds to
`127.0.0.1` by default and does not include accounts, teams, permissions, or
remote sync.

## Development

Install dependencies and run checks:

```sh
uv sync
uv run pytest
uv run ruff check .
uv run pre-commit install
```

The pre-commit hook runs ruff and pytest.

Project stack:

- Python package management: `uv`
- CLI: Typer and Rich
- Web UI: FastAPI, Jinja templates, and plain CSS
- Database: SQLite through Python `sqlite3`
- Tests: pytest
- Lint: ruff

Before changing behavior, read:

- `AGENTS.md`
- `memory/index.md`
- relevant `memory/areas/*.md`
- relevant `user_stories/*.md`

The repo memory and user stories are part of the project documentation, not
generated scratch notes.

## Maintainer Release

Before publishing, run the checks and build the release artifacts:

```sh
uv run pytest
uv run ruff check .
uv build --no-sources
```

This creates a source distribution and wheel under `dist/`.

The wheel includes only the runtime `narad` package, including the web UI
templates and CSS. The source distribution is intentionally trimmed to source
files and public package metadata:

- `src/narad/`
- `README.md`
- `LICENSE`
- `pyproject.toml`

Repo-local memory, user stories, artifacts, tests, and `uv.lock` are not shipped
in distribution artifacts.

Publish to PyPI after the project is configured:

```sh
uv publish
```

For automated releases, prefer PyPI Trusted Publishing from GitHub Actions over
long-lived PyPI tokens.

## Contributing

Contributions are welcome, especially when they keep Narad small and useful.

Good first areas:

- Improve CLI ergonomics.
- Tighten the local web UI.
- Add focused tests for store, CLI, or web behavior.
- Improve import/export workflows.
- Clarify docs for real personal CRM use cases.

Design principles:

- Keep source code as the source of truth.
- Keep CLI and web behavior aligned through `narad.store`.
- Prefer simple SQLite-backed behavior over premature platform features.
- Do not touch a user's real `~/.narad/narad.db` in tests.
- Use `NARAD_HOME` and `NARAD_DB` for isolated test data.

## AI Agent Usage

Agents should treat Narad as the user's local personal CRM and prefer the CLI
over direct SQLite writes.

Before adding a likely duplicate contact, search first:

```sh
narad search "asha acme"
narad show 1
```

Then record structured context through the CLI:

```sh
narad add contact "Asha Rao" --company "Acme Labs" --source linkedin --tag warm
narad add note "Discussed pilot timeline" --contact "Asha" --channel whatsapp
narad add task "Send pilot proposal" --due tomorrow --contact "Asha"
narad edit contact 1 --source conference --tag champion
narad done 3
```

Agent guidelines:

- Use contact IDs from `narad search`, `narad list contacts`, or `narad show`
  when a name is ambiguous.
- Store relationship origin in contact `--source`.
- Store event medium in note `--channel`.
- Record follow-ups as tasks instead of burying them only in note text.
- Use `NARAD_HOME` and `NARAD_DB` for sandboxed runs.

## Roadmap

Near-term ideas:

- Add practical import/export commands.
- Add backup helpers.
- Improve filtering and editing flows in the web UI.

Narad is intentionally not trying to become an enterprise CRM. Sync, hosted
multi-user access, and advanced reporting can wait until they clearly earn their
complexity.

## License

Narad is released under the MIT License. See [LICENSE](LICENSE).
