Metadata-Version: 2.4
Name: maris
Version: 0.2.2
Summary: Local Multi-Agent Repository Intelligence System
Author-email: Rohin Patel <rohin.patel@outlook.com>
License: MIT
Project-URL: Homepage, https://github.com/rohinp/maris
Project-URL: Documentation, https://github.com/rohinp/maris/docs
Project-URL: Repository, https://github.com/rohinp/maris
Project-URL: Issues, https://github.com/rohinp/maris/issues
Keywords: repository,intelligence,llm,code-analysis,local-first
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tree-sitter>=0.21.0
Requires-Dist: tree-sitter-python>=0.21.0
Requires-Dist: tree-sitter-java>=0.21.0
Requires-Dist: tree-sitter-scala>=0.21.0
Requires-Dist: tree-sitter-kotlin>=0.1.0
Requires-Dist: tree-sitter-javascript>=0.21.0
Requires-Dist: tree-sitter-typescript>=0.21.0
Requires-Dist: tree-sitter-go>=0.21.0
Requires-Dist: tree-sitter-bash>=0.21.0
Requires-Dist: tree-sitter-rust>=0.21.0
Requires-Dist: duckdb>=1.0.0
Requires-Dist: lancedb>=0.5.0
Requires-Dist: pylance>=0.9.0
Requires-Dist: pyarrow>=17.0.0
Requires-Dist: langchain>=0.1.0
Requires-Dist: langchain-community>=0.0.20
Requires-Dist: langgraph>=0.0.20
Requires-Dist: ollama>=0.4.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: watchdog>=4.0.0
Requires-Dist: gitpython>=3.1.0
Requires-Dist: rich>=13.7.0
Requires-Dist: click>=8.1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.2.0; extra == "dev"
Requires-Dist: mypy>=1.8.0; extra == "dev"
Requires-Dist: pre-commit>=3.6.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: license-file

# MARIS

MARIS is a local-first, multi-agent repository intelligence system for understanding source code. It indexes repositories with language-aware parsers, stores repository knowledge locally, and uses local Ollama models for search, Q&A, documentation, impact analysis, and implementation prompt generation.

The goal is to help developers reason about codebases without sending source code to external services. MARIS focuses on repository understanding rather than code generation, while the Prompt Generator Agent helps convert that understanding into implementation-ready prompts for another coding agent.

## Current Status

MARIS is an alpha-stage Python package.

Implemented:

- CLI entry point: `maris`
- Local storage with DuckDB metadata and LanceDB vectors
- Ollama-based embeddings and local model validation
- Parser implementations for Python, Java, Scala, Bash, JavaScript, TypeScript, Config files (YAML/JSON/TOML/INI), and Markdown
- Repository indexing, semantic search, symbol explanations, Q&A, documentation generation, and repository stats
- Git-based incremental indexing
- Impact analysis commands for impact, edge cases, test coverage, and breaking changes
- Prompt Generator Agent for turning a task or problem statement into a context-aware implementation prompt

Planned or incomplete:

- Kotlin, Go, and Rust parsers have tree-sitter grammars installed but parser implementations are not yet complete
- Git archaeology and architecture evolution agents are roadmap items
- Some secondary docs may lag the CLI; the root README should be treated as the current quick-start reference
- `AGENT.md` is contributor guidance and product direction, not an executable agent spec

## Requirements

- Python 3.11+
- Ollama running locally
- Required Ollama models:
  - `nomic-embed-text` for embeddings
  - `qwen2.5:7b` by default for Q&A and documentation

Install or start Ollama separately, then pull the default models:

```bash
ollama pull nomic-embed-text
ollama pull qwen2.5:7b
```

## Installation

For local development:

```bash
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
pip install -r requirements-dev.txt
pip install -e .
```

Alternatively, use the setup script:

```bash
./setup.sh
source venv/bin/activate
```

Verify the CLI:

```bash
maris --help
```

## Quick Start

Run MARIS from the repository you want to analyze. By default, MARIS stores project-specific data in `.maris/` in the current working directory unless `MARIS_DATA_DIR` is set.

### ⚠️ Important: Index First

**You must index your repository before using search, ask, explain, document, or prompt-generation workflows.** MARIS does not auto-index; indexing is an explicit step that builds the knowledge base.

```bash
# Step 1: Index your repository (required first step)
maris index src/ --recursive

# Step 2: Verify indexing completed
maris stats

# Step 3: Now you can use other commands
# Search indexed symbols
maris search "RepositoryKnowledge"

# Ask questions about your codebase
maris ask "How does indexing work?"

# Explain specific symbols
maris explain IndexingAgent

# Generate documentation
maris document src/maris/agents/indexing_agent.py --output docs/indexing_agent.md

# Generate an implementation-ready prompt for another AI coding agent
maris prompt "Add a CLI command that prints repository indexing health as Markdown"
```

### Incremental Indexing

After the initial index, use incremental indexing to update only changed files:

```bash
# Re-index only files that changed since last index
maris index --incremental
```

This is much faster than re-indexing the entire repository.

Impact analysis examples:

```bash
maris impact analyze --symbol "GitAgent.detect_changes"
maris impact edge-cases --file "src/maris/agents/git_agent.py"
maris impact tests --symbol "QAAgent.answer_question"
maris impact breaking-changes --symbol "RepositoryKnowledgeImpl"
```

Interactive Q&A:

```bash
maris interactive
```

Prompt generation examples:

```bash
maris prompt "Add a CLI command that prints repository indexing health as Markdown"
maris prompt "Add retry support to indexing" --context "Retry transient Ollama failures only"
maris prompt "Improve parser error handling" --output implementation-prompt.md
```

The generated prompt includes the original task, relevant code context, likely files, implementation requirements, edge cases to consider, test guidance, and an execution plan. It is designed to be handed to another AI coding agent.

## CLI Reference

Global options:

```bash
maris --config-file .env --skip-validation COMMAND
```

Commands:

- `maris index [PATH]`: index a file or directory
- `maris index --incremental`: index files changed since the last indexed commit
- `maris search QUERY`: semantic symbol search
- `maris explain SYMBOL_NAME`: explain a symbol with relevant indexed context
- `maris ask QUESTION`: ask a natural-language repository question
- `maris prompt TASK`: generate an implementation-ready prompt for another AI coding agent
- `maris impact analyze`: analyze callers, callees, affected files, and recommendations
- `maris impact edge-cases`: detect likely edge case risks
- `maris impact tests`: inspect test coverage signals
- `maris impact breaking-changes`: detect potential breaking change risks
- `maris document FILE_PATH`: generate Markdown documentation for a file
- `maris stats`: show indexed symbol counts
- `maris clear`: clear indexed metadata and vectors
- `maris interactive`: start an interactive Q&A session

Use command help for exact options:

```bash
maris COMMAND --help
maris impact COMMAND --help
```

## Configuration

Configuration is loaded in this order:

1. Environment variables with the `MARIS_` prefix
2. `.env` in the current directory
3. `~/.maris/.env`
4. Defaults

Common settings:

```bash
MARIS_DATA_DIR=.maris
MARIS_OLLAMA_HOST=http://localhost:11434
MARIS_EMBEDDING_MODEL=nomic-embed-text
MARIS_EMBEDDING_BATCH_SIZE=32
MARIS_QA_MODEL=qwen2.5:7b
MARIS_QA_TEMPERATURE=0.7
MARIS_QA_MAX_TOKENS=2048
MARIS_DOC_MODEL=qwen2.5:7b
MARIS_DOC_TEMPERATURE=0.3
MARIS_DOC_MAX_TOKENS=4096
MARIS_MAX_SEARCH_RESULTS=20
MARIS_MAX_CONTEXT_SYMBOLS=10
MARIS_ENABLE_CACHING=true
MARIS_PARALLEL_INDEXING=false
MARIS_LOG_LEVEL=INFO
```

For first-time setup, `maris index ... --auto-pull` can pull missing Ollama models automatically. Use `--skip-validation` only when you intentionally want to bypass Ollama and model checks.

## Architecture

MARIS is organized around a shared repository knowledge layer:

```text
Source repository
    -> Indexing Agent
    -> Repository Knowledge Layer
       -> DuckDB metadata store
       -> LanceDB vector store
       -> Ollama embeddings
    -> Specialized agents
       -> Q&A Agent
       -> Documentation Agent
       -> Git Agent
       -> Impact Analysis Agent
       -> Prompt Generator Agent
```

Core source layout:

```text
src/maris/
  agents/       specialized agents and orchestrator
  cli/          Click-based CLI
  config/       configuration loading
  core/         domain models
  embeddings/   Ollama embedding service
  indexing/     Tree-sitter parsers and parser factory
  knowledge/    repository knowledge service
  storage/      DuckDB and LanceDB adapters
  utils/        shared validation helpers
```

## Development

Run tests:

```bash
pytest
```

Run targeted tests:

```bash
pytest tests/test_python_parser.py
pytest tests/test_orchestrator_agent.py
```

Formatting and linting tools are configured in `pyproject.toml`:

```bash
black src tests
ruff check src tests
```

## Contributor Guidance

`AGENT.md` contains contributor guidance and product direction. The key expectations are:

- Read `.codex/project-profile.md` before changing architecture or design direction
- Read relevant files in `.codex/specs/` before changing behavior
- Preserve the local-first, retrieval-first, symbol-aware design
- Prefer deterministic workflows and specialized agents over broad autonomous loops
- Update specs when behavior, acceptance criteria, API contracts, or domain rules change

## Additional Docs

- [Installation Guide](docs/INSTALLATION.md)
- [Configuration](docs/CONFIGURATION.md)
- [Architecture](docs/ARCHITECTURE.md)
- [Project Walkthrough](docs/PROJECT_WALKTHROUGH.md)
- [Git Agent](docs/GIT_AGENT.md)
- [Impact Analysis Agent](docs/IMPACT_ANALYSIS_AGENT.md)
- [Prompt Generator Agent](docs/PROMPT_GENERATOR_AGENT.md)
- [Multi-Language Support](docs/MULTI_LANGUAGE_SUPPORT.md)
