Metadata-Version: 2.4
Name: foundry-cli-agent
Version: 0.3.1
Summary: A local-first AI coding agent with one gateway for five LLM providers and a self-provisioning database.
Author: FoundryCLI
License-Expression: MIT
Project-URL: Documentation, https://github.com/am1t-verma/opencode_foundry#readme
Project-URL: Source, https://github.com/am1t-verma/opencode_foundry
Project-URL: Issues, https://github.com/am1t-verma/opencode_foundry/issues
Keywords: ai,agent,llm,cli,coding-assistant,ollama,bedrock,openai,anthropic
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: alembic>=1.13
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: sqlalchemy>=2.0
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == "bedrock"
Provides-Extra: postgres
Requires-Dist: psycopg[binary]>=3.1; extra == "postgres"
Provides-Extra: dev
Requires-Dist: boto3>=1.34; extra == "dev"
Requires-Dist: psycopg[binary]>=3.1; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Dynamic: license-file

# FoundryCLI

A local-first AI coding agent. It reads, writes and edits files, searches
codebases, runs shell commands, and streams its output as it happens.

Runs on your own machine with a local model — **no cloud account and no
database server required**.

---

## Install

Install the tool. The package carries everything it needs — there is
nothing to clone and nothing else to set up:

```bash
pip install foundry-cli-agent
```

That gives you the `foundry` command. Without installing, every example
below works as `python -m foundry.cli.main ...`.

Prefer a local build, or the release is not on PyPI yet? Build the wheel
from a checkout (`pip install build` first):

```bash
python -m build    # writes dist/foundrycli-0.3.0-py3-none-any.whl
pip install dist/foundrycli-0.3.0-py3-none-any.whl
```

Working on the source? An editable install from a checkout also brings
in the test and lint tooling:

```bash
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

Optional extras:

```bash
pip install "foundrycli[bedrock]"    # AWS Bedrock needs boto3
pip install "foundrycli[postgres]"   # PostgreSQL needs psycopg
```

From a checkout, write `-e ".[bedrock]"` and `-e ".[postgres]"` instead.

## Quick start

```bash
foundry init        # creates the database and schema, reports the provider
foundry chat        # start the agent
foundry chat "list the python files in foundry/"
```

For a local model:

```bash
ollama serve
ollama pull qwen2.5:3b     # a tool-capable model
```

## Commands

| Command | What it does |
|---------|--------------|
| `foundry init` | Create the database and schema, then report the LLM provider. |
| `foundry status` | Show the database state and which provider is active. |
| `foundry providers` | List every backend and whether it is reachable. |
| `foundry setup` | The settings screen — provider, API key, model, theme. |
| `foundry chat` | Start the interactive agent. |
| `foundry chat "prompt"` | Run a single prompt. |

Inside the REPL: `exit`, `clear` (new conversation), `status` (details),
`settings` (open the settings screen).

`--provider <name>` forces a backend for one run:

```bash
foundry --provider anthropic chat "hello"
```

## Settings

`foundry setup` opens a small terminal UI. Pick a provider, type the key,
choose a theme — it writes to `.env` for you, and the key is never echoed
to the screen.

```
FoundryCLI - settings

  > Provider      currently auto
    API key       enter a key for a provider
    Model         change the model name
    Theme         currently default
    Show current settings
    Quit
```

You do not have to use a cloud provider. `ollama` needs no key at all.

Writing to `.env` never damages the rest of the file — the comments,
blank lines and commented-out alternatives all survive.

Six themes ship with the tool: `default`, `midnight`, `amber`, `mono`,
`forest` and `violet`. `NO_COLOR` is respected.

## The live status view

While a task runs, a small panel under the answer shows the elapsed time,
the provider, the step count and the recent tool calls:

```
 v list the files in foundry/llm
   12.5s  ·  auto  ·  [##--------] step
   list_directory ok
```

It repaints in place, so it does not fill the scrollback. Turn it off with
`foundry chat --no-status` when you are piping the output somewhere.

## The LLM gateway

One gateway, five backends. Every one of them speaks the same
provider-neutral protocol, so the agent loop never changes.

| Provider | API | Key | Notes |
|----------|-----|-----|-------|
| **Ollama** | OpenAI-compatible | – | Local, free. Needs a tool-capable model such as `qwen2.5:3b`. |
| **AWS Bedrock** | Converse | AWS creds | Uses the standard AWS credential chain. |
| **OpenAI** | Chat Completions | `OPENAI_API_KEY` | |
| **Anthropic** | Messages | `ANTHROPIC_API_KEY` | Native Messages format, not OpenAI-compatible. |
| **MiniMax** | Chat Completions | `MINIMAX_API_KEY` | OpenAI-compatible. |
| **auto** | – | – | Probes each backend and uses the first that answers. |

```bash
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...
```

Each provider has its own model and base URL in `.env`, so switching
backends never leaks a stale setting:

```ini
OLLAMA_MODEL=qwen2.5:3b
OLLAMA_BASE_URL=http://localhost:11434/v1
BEDROCK_MODEL_ID=moonshotai.kimi-k2.5
AWS_REGION=us-east-1
OPENAI_MODEL=gpt-4o-mini
ANTHROPIC_MODEL=claude-sonnet-4-5
MINIMAX_MODEL=MiniMax-M2
```

Check what is reachable at any time:

```bash
foundry providers
```

## The database

`DATABASE_URL` decides the backend, and the database creates itself:

- **SQLite** (default) — a `foundry.db` file next to where you are
  working. In a source checkout that is the checkout root (the folder
  holding `pyproject.toml`); for an installed copy it is the directory
  you ran the command from. It is never written inside `site-packages`.
- **PostgreSQL** — if the database is missing, FoundryCLI connects to the
  `postgres` maintenance database and issues `CREATE DATABASE`, then
  applies the schema.

Migrations ship inside the package, at `foundry/migrations/`, and run
automatically at startup. An installed copy brings its own database up to
date; the root `alembic.ini` is only for running `alembic` by hand during
development.

## Tools

| Tool | Permission | Purpose |
|------|------------|---------|
| `read_file` | read | Read a text file, with offset and limit. |
| `write_file` | write | Create a file or write complete content. |
| `edit_file` | write | Replace one exact piece of text. Keeps a `.backup`. |
| `delete_file` | write | Delete a file. |
| `search_files` | read | Search for text inside a directory. |
| `list_directory` | read | List a directory, optionally recursive. |
| `ast_analysis` | read | Imports, classes, functions, and calls of a Python file. |
| `symbol_search` | read | Find a class or function by name. |
| `project_structure` | read | A tree view of a project. |
| `run_command` | execute | Run a shell command. |

`write` and `execute` tools ask for approval before they run. Every file
tool is confined to the project root by `PathPolicy`.

## Development

```bash
python run_checks.py    # tests, compile check, unused imports, ruff
pytest tests/           # just the tests
```

372 tests, 0 failing.

The tests and the documentation live in the repository, not in the
package. `pip install foundrycli` gives you the tool; the test suite and
the guides are for working on the source.

## License

MIT
