How eleshvaishnav/parmana works
1. Overall shape
Parmana is not a client-server app. It is a local-first AI assistant package with a small amount of packaging/website infrastructure around it. The core runtime is meant to run on a user’s machine, with no backend API in the steady state.
2. Primary runtime boundary
The main execution path is the CLI assistant started via parmana_bot.py. That script is the likely entrypoint for interactive chat and for wiring together prompt loading, conversation state, and calls into the local model runtime.
3. Local model definition
config/Modelfile is the model/personality boundary. In this repo, it likely defines the assistant’s base behavior and how the underlying local model should be packaged or invoked. This is where the “Parmana” persona is separated from the generic model engine.
4. System prompt and identity layer
system_prompt.txt holds the assistant’s core instructions/identity. Architecturally, this is a distinct input to the runtime: it shapes response style, language behavior, and guardrails without embedding that text directly into code.
5. Memory subsystem
memory/memory.py is the persistent state layer. It likely manages conversation history or user-specific memory across sessions, which means the assistant has a separate data boundary for state rather than being stateless chat only.
6. Platform-specific installers
install.sh, install.ps1, uninstall.sh, and uninstall.ps1 form the distribution/bootstrap layer. Their job is to provision the local environment, detect machine capabilities, fetch the right model, and install/remove the parmana command. This is the main operational boundary between “repo contents” and “usable app.”
7. Hardware-aware model selection
The README describes RAM-based model selection (0.6B, 2B, 4B, 8B). That implies the installers are responsible for the first major decision in the flow: choose model size based on available resources, then download once and run locally thereafter.
8. Data flow at runtime
The intended flow is: user launches parmana → parmana_bot.py loads system_prompt.txt and memory state → local model is invoked using the config-defined model setup → response is returned to the terminal → memory is updated. No external API is part of the normal chat loop.
9. Persistence and offline behavior
The design emphasizes offline use after initial setup. The only expected network dependency is the first-time download of the model and any installation assets. After that, the assistant is supposed to function entirely on-device.
10. Web/marketing surface
index.html plus the GitHub Pages workflows under .github/workflows/ indicate a separate static site boundary. This is for project presentation/documentation, not the assistant runtime itself.
11. Repository operations and CI
The GitHub Actions files are for publishing the static site. They are operational infrastructure, not application logic. They support the public-facing landing page and repo maintenance, but they do not participate in conversation processing.
12. Security and verification artifacts
Files like SECURITY.md, CODE_OF_CONDUCT.md, issue templates, and the Google verification HTML are repository governance/ownership artifacts. They support the project’s public presence but are outside the runtime architecture.
13. What to draw in an architecture diagram
The diagram should center on a local user machine containing: the CLI entrypoint, prompt/config files, memory store, and the local model runtime. Surround that with an install/bootstrap path that fetches the right model once, plus a separate static website / GitHub Pages lane for project distribution.
14. Key architectural takeaway
Parmana’s core architecture is: static packaging + local model execution + local memory persistence. There is no central application server; the repository mainly orchestrates how the assistant is installed, personalized, and run on the user’s device.
Main entry points: parmana_bot.py CLI bot · index.html Landing page · install.sh Install script · install.ps1 PowerShell install
Components 20
Local assistant
Core on-device chat assistant runtime and its state/prompt inputs.
- CLI bot · Interactive command-line assistant entrypoint and runtime coordinator.
parmana_bot.py - System prompt · Core identity and behavior instructions loaded at runtime.
system_prompt.txt - Modelfile · Local model/persona packaging and invocation definition.
config/Modelfile - Memory · Conversation or user state persisted across sessions.
memory/memory.py - Local model · On-device model runtime used to generate responses.
- User terminal · Where the user launches the assistant and reads responses.
Installers
Platform-specific setup and removal path for the local command and model.
- Install script · Unix bootstrap script for provisioning the assistant and model.
install.sh - PowerShell install · Windows bootstrap script for provisioning the assistant and model.
install.ps1 - Uninstall script · Unix removal script for uninstalling the assistant setup.
uninstall.sh - PowerShell uninstall · Windows removal script for uninstalling the assistant setup.
uninstall.ps1 - README · Primary setup and model-selection guidance for users and installers.
README.md
Site publishing
Static site and GitHub Pages automation for project presentation.
- Landing page · Public project website and marketing surface.
index.html - Pages workflow · GitHub Actions workflow for publishing the static site.
.github/workflows/jekyll-gh-pages.yml - Static workflow · GitHub Actions workflow supporting static site publication.
.github/workflows/static.yml
Project governance
Repository policy and contribution/verification artifacts.
- Issue template · Repository template for issue reporting and community workflow.
ISSUE_TEMPLATE.md - Bug template · Structured bug report template for contributors.
.github/ISSUE_TEMPLATE/bug_report.md - Security · Security policy and reporting guidance.
SECURITY.md - Code of conduct · Community behavior and contribution standards.
CODE_OF_CONDUCT.md - Contributing · Contribution guidelines for the project.
CONTRIBUTING.md - Verify HTML · Ownership verification artifact for search or hosting services.
google21d6399e385c3db7.html
Connections 23
- User terminal → CLI bot: launches · User starts the assistant from the terminal.
- CLI bot → System prompt: loads · Runtime reads the assistant identity and guardrails.
- CLI bot → Memory: reads/writes · Conversation state is persisted between sessions.
- CLI bot → Modelfile: uses · CLI runtime uses the local model packaging definition.
- Modelfile → Local model: configures · Model file defines how the local model is packaged or invoked.
- CLI bot → Local model: invokes · Interactive requests are sent to the local model runtime.
- Local model → CLI bot: returns · Generated responses flow back to the CLI assistant.
- Install script → README: guided by · Unix installation follows the documented setup and model choice.
- PowerShell install → README: guided by · Windows installation follows the documented setup and model choice.
- Install script → CLI bot: installs · Bootstrap path installs the assistant command on Unix.
- PowerShell install → CLI bot: installs · Bootstrap path installs the assistant command on Windows.
- Install script → Local model: fetches · Installer downloads the selected local model during first setup.
- PowerShell install → Local model: fetches · Installer downloads the selected local model during first setup.
- Uninstall script → CLI bot: removes · Unix uninstall path removes the installed assistant command.
- PowerShell uninstall → CLI bot: removes · Windows uninstall path removes the installed assistant command.
- Landing page → Pages workflow: published by · Landing page is deployed through the Pages workflow.
- Landing page → Static workflow: published by · Static site publication is handled by repository automation.
- Pages workflow → Landing page: deploys · Workflow publishes the static landing page.
- Static workflow → Landing page: deploys · Workflow publishes the static landing page.
- Issue template → Bug template: uses · General issue reporting is complemented by a bug-specific template.
- Security → Contributing: supports · Governance documents define project participation boundaries.
- Code of conduct → Contributing: supports · Community standards complement contribution guidance.
- Verify HTML → Landing page: verifies · Ownership verification artifact supports the public site.