# Agentik Framework
**Agentik** is a CLI‑first, modular agent framework that runs LLMs via **OpenRouter**. It focuses on developer ergonomics: clean configs, a batteries‑included CLI, safe tool execution, rich transcripts with run metadata, and a `dev` profile with auto‑rerun watching for fast iteration.
---
## Highlights
* **CLI‑first workflow**: `agentik run`, `agentik dev watch`, `agentik tools ...`
* **OpenRouter integration**: one key → many models
* **Agent loop**: *plan → (optional tool) → reflect → finalize*
* **Pluggable tooling** (via entry points) with built‑ins:
* `http_fetch` — GET with caching + limits
* `html_to_text` — HTML → text
* `write_file` — safe file writer
* **Policies** enforced per tool call: `allow_network`, `allow_filesystem`
* **Transcripts**: JSONL with `meta_start`/`meta_end` (tokens, cost estimate, timings, tags)
* **Run profiles**: `fast`, `thorough`, `deterministic`, `creative`, `cheap`, `dev`
* **Dev watcher**: polling file watcher, auto‑rerun on save (no extra deps)
* **Memory**: file‑backed minimal memory (`json` or in‑memory `dict`)
---
## Installation
Requires **Python 3.10+**.
```bash
pip install agentik-framework
# for local development
pip install -e .[dev]
```
### OpenRouter API key
Set your key once (recommended):
**PowerShell (Windows):**
```powershell
setx OPENROUTER_API_KEY "sk-or-..."
# then restart your shell
```
Or via Agentik RC:
```powershell
agentik keys set openrouter sk-or-... --global
```
Verify your setup:
```powershell
agentik self-test
```
---
## End‑User Guide (PyPI + CLI)
Once you’ve installed the package from PyPI, you can use **Agentik** entirely from the **CLI**. Here’s a concise, step‑by‑step guide for end users.
### 1) Install
```bash
pip install agentik-framework
```
> Python **3.10+** required.
### 2) Set your OpenRouter API key (one time)
**Windows (PowerShell):**
```powershell
setx OPENROUTER_API_KEY "sk-or-XXXXXXXXXXXXXXXX"
# Open a new PowerShell window afterwards
```
**macOS/Linux (bash/zsh):**
```bash
echo 'export OPENROUTER_API_KEY="sk-or-XXXXXXXXXXXXXXXX"' >> ~/.bashrc
source ~/.bashrc
```
**Verify:**
```powershell
agentik self-test
agentik models list --filter gpt --refresh # optional network check
```
### 3) Create a project folder
```powershell
mkdir my-agent && cd my-agent
```
Initialize a basic layout (templates are bundled with the package):
```powershell
agentik init . --template basic --name "My Agent Project"
```
Generate a ready‑to‑run agent config (adds a file under `agents/`):
```powershell
agentik new agent research --template basic --tools http_fetch,html_to_text,write_file --with-tests --to .
```
Want to see available templates and tools?
```powershell
agentik template list
agentik tools list
```
### 4) Minimal config (if you prefer to paste one)
Create `agents/agent.yaml` with:
```yaml
agent:
name: ResearchBot
goal: "Research and summarize information."
loop:
max_steps: 3
reflect: true
llm:
model: openai/gpt-4o-mini
temperature: 0.3
memory:
type: json
path: ./memory/research.json
policies:
allow_network: true
allow_filesystem: true
tools:
- http_fetch
- html_to_text
- write_file
```
### 5) Run your agent
**Windows (PowerShell):**
```powershell
agentik run .\agents\agent.yaml `
-p "Summarize the main differences between GPT-4o and small LLMs in 5 bullets." `
--profile fast `
--stream `
--save-transcript .\runs\first-run.jsonl
```
**macOS/Linux:**
```bash
agentik run ./agents/agent.yaml \
-p "Summarize the main differences between GPT-4o and small LLMs in 5 bullets." \
--profile fast \
--stream \
--save-transcript ./runs/first-run.jsonl
```
**Handy flags:**
* `--profile fast|thorough|deterministic|creative|cheap|dev|none`
* `--model <openrouter-model-id>`
* `--temperature <float>`
* `--save-transcript <path>` — JSONL with metadata, tokens, timings, cost est.
* `--tag`, `--note`, `--run-id` — stored in transcript metadata
### 6) Use the dev watcher (auto re‑run on file changes)
> PowerShell tip: **quote your globs** to avoid expansion.
**Windows (PowerShell):**
```powershell
agentik dev watch .\agents\agent.yaml `
--prompt "Summarize this project in 3 bullets." `
--path . `
--include '**/*.py' --include '**/*.yaml' --include 'templates/**' `
--exclude '.venv/**' --exclude 'runs/**' `
--save-transcripts .\runs `
--profile dev `
--stream
```
**macOS/Linux:**
```bash
agentik dev watch ./agents/agent.yaml \
--prompt "Summarize this project in 3 bullets." \
--path . \
--include '**/*.py' --include '**/*.yaml' --include 'templates/**' \
--exclude '.venv/**' --exclude 'runs/**' \
--save-transcripts ./runs \
--profile dev \
--stream
```
### 7) Run tools directly (no agent loop)
```powershell
agentik tools run http_fetch --arg url=https://example.com --arg ttl=3600 --arg allow_network=true --json
agentik tools run html_to_text --arg "html=<p>Hello</p>" --arg keep_newlines=true --json
agentik tools run write_file --arg path=out\hello.txt --arg "content=Hello" --arg allow_filesystem=true --json
```
### 8) Memory helpers
```powershell
agentik memory init --type json --path .\memory\agentik.json
agentik memory recall --n 10 --config .\agents\agent.yaml
agentik memory summarize --n 20 --max-chars 1200 --config .\agents\agent.yaml
```
### 9) Batch prompts from a file
```powershell
agentik batch run .\prompts.jsonl --column prompt --out .\results.jsonl --model openai/gpt-4o-mini
```
`prompts.jsonl` example:
```json
{"prompt": "Write a haiku about summer."}
{"prompt": "One sentence on the solar eclipse."}
```
### 10) Common issues & fixes
**“Network error talking to OpenRouter.”**
Check your key in the same shell:
`echo $env:OPENROUTER_API_KEY` (PowerShell) / `echo $OPENROUTER_API_KEY` (bash).
Try: `agentik models list --refresh`. If you’re behind a proxy, set `HTTP_PROXY`/`HTTPS_PROXY`.
**Dev watcher says “unexpected extra arguments …”**
Quote your globs in PowerShell: `--include '**/*.py'` (with single quotes).
**Not seeing new CLI features after edits?**
Reinstall in editable mode from your project root: `pip install -e .[dev]`.
That’s it. After `pip install agentik-framework` you mainly interact through the `agentik` command. If you want examples or a minimal starter project scaffolded for you, just run `agentik init` and `agentik new agent …` and you’ll be up and running in minutes.
---
## Quick Start
Initialize a project:
```powershell
agentik init . --template basic --name "My Agent Project"
```
Scaffold an agent:
```powershell
agentik new agent research \
--template basic \
--tools http_fetch,html_to_text,write_file \
--with-tests
```
Create a minimal config (save as `agents/agent.yaml`):
```yaml
agent:
name: research
goal: "Research and summarize web sources"
loop:
max_steps: 4
reflect: true
llm:
model: openai/gpt-4o-mini
temperature: 0.2
memory:
type: json
path: ./memory/agent.json
policies:
allow_network: true
allow_filesystem: true
tools:
- http_fetch
- html_to_text
- write_file
```
Run it:
```powershell
agentik run .\agents\agent.yaml -p "Summarize the latest about OpenRouter rate limits"
```
---
## CLI Reference
### `agentik version`
Print the current version.
### `agentik self-test`
Environment sanity checks (Python, OS, OpenRouter key, RC path).
### `agentik init`
Initialize a project folder.
```bash
agentik init [PATH] --template basic --force --name "Project Name"
```
### `agentik run`
Run an agent loop with profiles and run metadata. (CONFIG is typically a YAML under `agents/`, e.g., `agents/research.yaml`.)
```bash
agentik run CONFIG \
-p "Prompt text" \
--model TEXT \
--temperature FLOAT \
--stream \
--dry-run \
--save-transcript PATH \
--profile [fast|thorough|deterministic|creative|cheap|dev|none] \
--tag TAG \
--note TEXT \
--run-id TEXT \
--obs-max-chars INT
```
### Keys
```bash
agentik keys set openrouter sk-or-... [--global|--local]
agentik keys show
```
### Models
```bash
agentik models list [--filter TEXT] [--refresh]
```
### New (scaffolding)
```bash
agentik new agent NAME \
--template basic \
--tools "t1,t2" \
--memory json \
--memory-path ./memory/agent.json \
--to . \
--with-tests \
--force
agentik new tool NAME \
--template python \
--to . \
--with-tests \
--force
```
### Templates
```bash
agentik template list
agentik template apply kind/name --to . --force --name MyArtifact
agentik template pull <git-or-zip-url> --to .
```
### Tools
```bash
agentik tools list
agentik tools info NAME
agentik tools run NAME --arg key=value --arg key2=value2 [--json]
```
### Validate
```bash
agentik validate file CONFIG.yaml \
--show-effective \
--model TEXT \
--temperature FLOAT \
--max-steps INT
```
### Batch
Process prompts from CSV or JSONL.
```bash
agentik batch run FILE \
--column prompt \
--out results.jsonl \
--model TEXT \
--temperature FLOAT
```
### Memory
```bash
agentik memory init --type json --path ./memory/agentik.json
agentik memory recall --n 10 [--config CONFIG.yaml]
agentik memory summarize --n 20 --max-chars 1200 [--config CONFIG.yaml]
agentik memory clear [--config CONFIG.yaml]
agentik memory path [--config CONFIG.yaml]
```
### Eval
Tiny harness to check expected substrings/regex.
```bash
agentik eval run FILE.jsonl --config CONFIG.yaml --out eval_results.jsonl
```
### Dev Watch (auto‑rerun)
Watches files and re‑runs on change — great during development.
```bash
agentik dev watch CONFIG \
-p "Prompt text" \
--prompt-file PATH \
--path PATH \ # repeatable (default .)
--include GLOB \ # repeatable (default python/yaml/md/templates/tools)
--exclude GLOB \ # repeatable
--interval 0.6 \
--debounce 0.5 \
--clear/--no-clear \
--stream/--no-stream \
--profile dev \
--save-transcripts DIR \
--obs-max-chars 800 \
--no-initial-run \
--tag TAG \ # repeatable (default "dev")
--note TEXT
```
Example (PowerShell):
```powershell
agentik dev watch .\agents\agent.yaml `
--prompt-file .\prompt.txt `
--path . `
--include **/*.py --include **/*.yaml --include templates/** `
--exclude .venv/** --exclude runs/** `
--save-transcripts .\runs `
--stream
```
---
## Tools & Policies
**Built‑in tools (selected):**
* `http_fetch(url, ttl, timeout, max_bytes, headers, allow_network)`
Returns `{ok, data, error, meta}` with `data.text`, `data.status`, and cache hints.
* `html_to_text(html, keep_newlines, drop_links, max_chars)`
Lightweight HTML → text (dependency‑free).
* `write_file(path, content, encoding, overwrite, allow_abs, allow_filesystem)`
Safe writer with sandboxing and system‑path guards.
**Policies (YAML):**
```yaml
policies:
allow_network: true
allow_filesystem: false
```
If a tool requires a disabled capability, Agentik blocks it and records an observation.
---
## Transcripts & Cost
Each run can append JSONL records via `--save-transcript`. Files include:
* `meta_start`: run id, profile, tags, agent, model, policies, memory path
* Tool calls and assistant responses
* `meta_end`: timings (planner/tools/reflect), tokens (prompt/completion/total), **estimated cost**
Cost is derived from OpenRouter pricing when available. You can override with env vars:
```powershell
# USD per 1K tokens
$env:AGENTIK_PRICE_PROMPT_PER_1K = "0.50"
$env:AGENTIK_PRICE_COMPLETION_PER_1K = "1.50"
```
---
## Configuration Reference (YAML)
```yaml
agent:
name: my-agent
goal: "Help with tasks."
loop:
max_steps: 4
reflect: true
llm:
model: openai/gpt-4o-mini
temperature: 0.2
memory:
type: json # json | dict
path: ./memory/agent.json
policies:
allow_network: true
allow_filesystem: false
tools:
- http_fetch
- html_to_text
```
---
---
# Agentik CLI — All Command Reference
A clean, practical guide to the `agentik` command‑line interface. Use this to initialize projects, scaffold agents/tools, run and iterate, manage config, and evaluate.
**Typical workflow:** `init → new → run → dev`
---
## Table of Contents
1. [Basic Information](#basic-information)
2. [Project Setup](#project-setup)
3. [Core Functionality](#core-functionality)
4. [Configuration & Management](#configuration--management)
5. [Data & Evaluation](#data--evaluation)
---
## Basic Information
Commands that show tool and environment details.
### `version`
Shows the installed version of the Agentik CLI.
```bash
agentik version
```
### `self-test`
Checks whether your environment (Python/OS/API keys) is set up correctly.
```bash
agentik self-test
```
---
## Project Setup
Create projects, agents, and tools from templates.
### `init`
Initialize a new project directory with the standard structure (`agents/`, `tools/`, etc.).
**Example: Create a project in a folder named `my-first-project`.**
```bash
agentik init my-first-project
```
### `new`
Scaffold new files from templates.
#### `new agent`
Create a new agent YAML configuration.
**Example: Inside your project, create an agent named `researcher` that uses the `web_search` tool.**
```bash
cd my-first-project
agentik new agent researcher --tools "web_search" --to ./agents
```
#### `new tool`
Create a new custom tool (Python file).
**Example: Create a tool named `calculator` in `./tools`.**
```bash
agentik new tool calculator --to ./tools
```
### `template`
Manage built-in and third‑party templates.
#### `template list`
Show all available templates for projects, agents, and tools.
```bash
agentik template list
```
#### `template apply`
Apply a specific template to a directory.
```bash
agentik template apply agent/basic --to ./agents --name "my-basic-agent"
```
---
## Core Functionality
Run and iterate on your agents.
### `run`
Run an agent using a specific configuration file to complete a task.
**Example: Run the `researcher` agent with a prompt and save the transcript.**
```bash
agentik run .\agents\researcher.yaml \
-p "What is the current time in India?" \
--save-transcript .\runs\research-run.jsonl
```
### `dev`
Watch project files for changes and automatically re-run your agent for rapid iteration.
**Example: Re-run the `researcher` agent whenever a `.py` or `.yaml` file is saved.**
```bash
agentik dev watch .\agents\researcher.yaml --prompt "Summarize the agentik framework in 5 bullets."
```
> **Note:** If you encounter a `generator` error while streaming, add `--no-stream`.
---
## Configuration & Management
Manage API keys, models, tools, validation, and configuration paths.
### `keys`
Store and view API keys (e.g., OpenRouter) used by Agentik.
**Set a key:**
```bash
# Replace with your actual key
agentik keys set sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx
```
**Show the active key (from env and `.agentikrc`):**
```bash
agentik keys show
```
### `models`
List available models (via OpenRouter) with optional filtering.
**Example: List models containing "claude".**
```bash
agentik models list --filter "claude"
```
### `tools`
Discover and test tools locally.
**List discovered tools:**
```bash
agentik tools list
```
**Run a specific tool with arguments (useful for testing):**
```bash
agentik tools run file_reader --arg "path=./README.md"
```
### `validate`
Validate an agent YAML configuration file.
```bash
agentik validate file .\agents\researcher.yaml
```
### `config`
Locate configuration file paths used by Agentik (`.agentikrc`).
**Global config path:**
```bash
agentik config path --global
```
**Local project config path:**
```bash
agentik config path --local
```
---
## Data & Evaluation
Work with agent memory, batch processing, and test evaluations.
### `memory`
Interact with an agent’s memory (requires a config file to target the correct memory store).
**Recall the last N items:**
```bash
agentik memory recall --config .\agents\researcher.yaml --n 5
```
**Clear memory:**
```bash
agentik memory clear --config .\agents\researcher.yaml
```
### `batch`
Run a set of prompts from a CSV or JSONL file through a specified model.
**Example: Prepare `prompts.csv`**
```text
id,question
1,"What is 2+2?"
2,"What is the capital of France?"
```
**Run the batch (using the `question` column):**
```bash
agentik batch run prompts.csv --column "question" --out results.jsonl --model "openai/gpt-4o-mini"
```
### `eval`
Evaluate an agent against test cases.
**Example: Create `tests.jsonl`**
```json
{"prompt": "What is the capital of Germany?", "expect_contains": ["Berlin"]}
{"prompt": "Calculate 5*5.", "expect_regex": "25"}
```
**Run the evaluation:**
```bash
agentik eval run tests.jsonl --config .\agents\researcher.yaml --out eval-results.jsonl
```
---
### Quick Tips
* Use `--no-stream` if your terminal shows streaming-related generator errors.
* Keep agent configs small and composable; prefer separate YAMLs for different roles.
* Commit `.agentikrc` cautiously; consider environment variables for secrets in CI/CD.
---
## Development
* **Lint/format:** `ruff check .` and `black .`
* **Tests:** `pytest -q`
* **Build:** `python -m build`
* **Publish:** `twine upload dist/*`
---
## Authors
* Vinay Joshi — [joshivinay822@gmail.com](mailto:joshivinay822@gmail.com)
* Avinash Raghuvanshi — [avi95461@gmail.com](mailto:avi95461@gmail.com)
## License
[MIT](LICENSE)
---
**Happy building with Agentik!**
---
Raw data
{
"_id": null,
"home_page": null,
"name": "agentik-framework",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "agents, cli, llm, openrouter, framework, automation",
"author": null,
"author_email": "Vinay Joshi <joshivinay822@gmail.com>, Avinash Raghuvanshi <avi95461@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/de/3a/a008b6d1eb8f35ee988b25e76f9059d2dbd5005eaf9f8e3d9ecbf5200399/agentik_framework-0.1.9.tar.gz",
"platform": null,
"description": "# Agentik Framework\r\n\r\n**Agentik** is a CLI\u2011first, modular agent framework that runs LLMs via **OpenRouter**. It focuses on developer ergonomics: clean configs, a batteries\u2011included CLI, safe tool execution, rich transcripts with run metadata, and a `dev` profile with auto\u2011rerun watching for fast iteration.\r\n\r\n---\r\n\r\n## Highlights\r\n\r\n* **CLI\u2011first workflow**: `agentik run`, `agentik dev watch`, `agentik tools ...`\r\n* **OpenRouter integration**: one key \u2192 many models\r\n* **Agent loop**: *plan \u2192 (optional tool) \u2192 reflect \u2192 finalize*\r\n* **Pluggable tooling** (via entry points) with built\u2011ins:\r\n\r\n * `http_fetch` \u2014 GET with caching + limits\r\n * `html_to_text` \u2014 HTML \u2192 text\r\n * `write_file` \u2014 safe file writer\r\n* **Policies** enforced per tool call: `allow_network`, `allow_filesystem`\r\n* **Transcripts**: JSONL with `meta_start`/`meta_end` (tokens, cost estimate, timings, tags)\r\n* **Run profiles**: `fast`, `thorough`, `deterministic`, `creative`, `cheap`, `dev`\r\n* **Dev watcher**: polling file watcher, auto\u2011rerun on save (no extra deps)\r\n* **Memory**: file\u2011backed minimal memory (`json` or in\u2011memory `dict`)\r\n\r\n---\r\n\r\n## Installation\r\n\r\nRequires **Python 3.10+**.\r\n\r\n```bash\r\npip install agentik-framework\r\n\r\n# for local development\r\npip install -e .[dev]\r\n```\r\n\r\n### OpenRouter API key\r\n\r\nSet your key once (recommended):\r\n\r\n**PowerShell (Windows):**\r\n\r\n```powershell\r\nsetx OPENROUTER_API_KEY \"sk-or-...\"\r\n# then restart your shell\r\n```\r\n\r\nOr via Agentik RC:\r\n\r\n```powershell\r\nagentik keys set openrouter sk-or-... --global\r\n```\r\n\r\nVerify your setup:\r\n\r\n```powershell\r\nagentik self-test\r\n```\r\n\r\n---\r\n\r\n## End\u2011User Guide (PyPI + CLI)\r\n\r\nOnce you\u2019ve installed the package from PyPI, you can use **Agentik** entirely from the **CLI**. Here\u2019s a concise, step\u2011by\u2011step guide for end users.\r\n\r\n### 1) Install\r\n\r\n```bash\r\npip install agentik-framework\r\n```\r\n\r\n> Python **3.10+** required.\r\n\r\n### 2) Set your OpenRouter API key (one time)\r\n\r\n**Windows (PowerShell):**\r\n\r\n```powershell\r\nsetx OPENROUTER_API_KEY \"sk-or-XXXXXXXXXXXXXXXX\"\r\n# Open a new PowerShell window afterwards\r\n```\r\n\r\n**macOS/Linux (bash/zsh):**\r\n\r\n```bash\r\necho 'export OPENROUTER_API_KEY=\"sk-or-XXXXXXXXXXXXXXXX\"' >> ~/.bashrc\r\nsource ~/.bashrc\r\n```\r\n\r\n**Verify:**\r\n\r\n```powershell\r\nagentik self-test\r\nagentik models list --filter gpt --refresh # optional network check\r\n```\r\n\r\n### 3) Create a project folder\r\n\r\n```powershell\r\nmkdir my-agent && cd my-agent\r\n```\r\n\r\nInitialize a basic layout (templates are bundled with the package):\r\n\r\n```powershell\r\nagentik init . --template basic --name \"My Agent Project\"\r\n```\r\n\r\nGenerate a ready\u2011to\u2011run agent config (adds a file under `agents/`):\r\n\r\n```powershell\r\nagentik new agent research --template basic --tools http_fetch,html_to_text,write_file --with-tests --to .\r\n```\r\n\r\nWant to see available templates and tools?\r\n\r\n```powershell\r\nagentik template list\r\nagentik tools list\r\n```\r\n\r\n### 4) Minimal config (if you prefer to paste one)\r\n\r\nCreate `agents/agent.yaml` with:\r\n\r\n```yaml\r\nagent:\r\n name: ResearchBot\r\n goal: \"Research and summarize information.\"\r\n loop:\r\n max_steps: 3\r\n reflect: true\r\n\r\nllm:\r\n model: openai/gpt-4o-mini\r\n temperature: 0.3\r\n\r\nmemory:\r\n type: json\r\n path: ./memory/research.json\r\n\r\npolicies:\r\n allow_network: true\r\n allow_filesystem: true\r\n\r\ntools:\r\n - http_fetch\r\n - html_to_text\r\n - write_file\r\n```\r\n\r\n### 5) Run your agent\r\n\r\n**Windows (PowerShell):**\r\n\r\n```powershell\r\nagentik run .\\agents\\agent.yaml `\r\n -p \"Summarize the main differences between GPT-4o and small LLMs in 5 bullets.\" `\r\n --profile fast `\r\n --stream `\r\n --save-transcript .\\runs\\first-run.jsonl\r\n```\r\n\r\n**macOS/Linux:**\r\n\r\n```bash\r\nagentik run ./agents/agent.yaml \\\r\n -p \"Summarize the main differences between GPT-4o and small LLMs in 5 bullets.\" \\\r\n --profile fast \\\r\n --stream \\\r\n --save-transcript ./runs/first-run.jsonl\r\n```\r\n\r\n**Handy flags:**\r\n\r\n* `--profile fast|thorough|deterministic|creative|cheap|dev|none`\r\n* `--model <openrouter-model-id>`\r\n* `--temperature <float>`\r\n* `--save-transcript <path>` \u2014 JSONL with metadata, tokens, timings, cost est.\r\n* `--tag`, `--note`, `--run-id` \u2014 stored in transcript metadata\r\n\r\n### 6) Use the dev watcher (auto re\u2011run on file changes)\r\n\r\n> PowerShell tip: **quote your globs** to avoid expansion.\r\n\r\n**Windows (PowerShell):**\r\n\r\n```powershell\r\nagentik dev watch .\\agents\\agent.yaml `\r\n --prompt \"Summarize this project in 3 bullets.\" `\r\n --path . `\r\n --include '**/*.py' --include '**/*.yaml' --include 'templates/**' `\r\n --exclude '.venv/**' --exclude 'runs/**' `\r\n --save-transcripts .\\runs `\r\n --profile dev `\r\n --stream\r\n```\r\n\r\n**macOS/Linux:**\r\n\r\n```bash\r\nagentik dev watch ./agents/agent.yaml \\\r\n --prompt \"Summarize this project in 3 bullets.\" \\\r\n --path . \\\r\n --include '**/*.py' --include '**/*.yaml' --include 'templates/**' \\\r\n --exclude '.venv/**' --exclude 'runs/**' \\\r\n --save-transcripts ./runs \\\r\n --profile dev \\\r\n --stream\r\n```\r\n\r\n### 7) Run tools directly (no agent loop)\r\n\r\n```powershell\r\nagentik tools run http_fetch --arg url=https://example.com --arg ttl=3600 --arg allow_network=true --json\r\nagentik tools run html_to_text --arg \"html=<p>Hello</p>\" --arg keep_newlines=true --json\r\nagentik tools run write_file --arg path=out\\hello.txt --arg \"content=Hello\" --arg allow_filesystem=true --json\r\n```\r\n\r\n### 8) Memory helpers\r\n\r\n```powershell\r\nagentik memory init --type json --path .\\memory\\agentik.json\r\nagentik memory recall --n 10 --config .\\agents\\agent.yaml\r\nagentik memory summarize --n 20 --max-chars 1200 --config .\\agents\\agent.yaml\r\n```\r\n\r\n### 9) Batch prompts from a file\r\n\r\n```powershell\r\nagentik batch run .\\prompts.jsonl --column prompt --out .\\results.jsonl --model openai/gpt-4o-mini\r\n```\r\n\r\n`prompts.jsonl` example:\r\n\r\n```json\r\n{\"prompt\": \"Write a haiku about summer.\"}\r\n{\"prompt\": \"One sentence on the solar eclipse.\"}\r\n```\r\n\r\n### 10) Common issues & fixes\r\n\r\n**\u201cNetwork error talking to OpenRouter.\u201d**\r\nCheck your key in the same shell:\r\n`echo $env:OPENROUTER_API_KEY` (PowerShell) / `echo $OPENROUTER_API_KEY` (bash).\r\nTry: `agentik models list --refresh`. If you\u2019re behind a proxy, set `HTTP_PROXY`/`HTTPS_PROXY`.\r\n\r\n**Dev watcher says \u201cunexpected extra arguments \u2026\u201d**\r\nQuote your globs in PowerShell: `--include '**/*.py'` (with single quotes).\r\n\r\n**Not seeing new CLI features after edits?**\r\nReinstall in editable mode from your project root: `pip install -e .[dev]`.\r\n\r\nThat\u2019s it. After `pip install agentik-framework` you mainly interact through the `agentik` command. If you want examples or a minimal starter project scaffolded for you, just run `agentik init` and `agentik new agent \u2026` and you\u2019ll be up and running in minutes.\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\nInitialize a project:\r\n\r\n```powershell\r\nagentik init . --template basic --name \"My Agent Project\"\r\n```\r\n\r\nScaffold an agent:\r\n\r\n```powershell\r\nagentik new agent research \\\r\n --template basic \\\r\n --tools http_fetch,html_to_text,write_file \\\r\n --with-tests\r\n```\r\n\r\nCreate a minimal config (save as `agents/agent.yaml`):\r\n\r\n```yaml\r\nagent:\r\n name: research\r\n goal: \"Research and summarize web sources\"\r\n loop:\r\n max_steps: 4\r\n reflect: true\r\n\r\nllm:\r\n model: openai/gpt-4o-mini\r\n temperature: 0.2\r\n\r\nmemory:\r\n type: json\r\n path: ./memory/agent.json\r\n\r\npolicies:\r\n allow_network: true\r\n allow_filesystem: true\r\n\r\ntools:\r\n - http_fetch\r\n - html_to_text\r\n - write_file\r\n```\r\n\r\nRun it:\r\n\r\n```powershell\r\nagentik run .\\agents\\agent.yaml -p \"Summarize the latest about OpenRouter rate limits\"\r\n```\r\n\r\n---\r\n\r\n## CLI Reference\r\n\r\n### `agentik version`\r\n\r\nPrint the current version.\r\n\r\n### `agentik self-test`\r\n\r\nEnvironment sanity checks (Python, OS, OpenRouter key, RC path).\r\n\r\n### `agentik init`\r\n\r\nInitialize a project folder.\r\n\r\n```bash\r\nagentik init [PATH] --template basic --force --name \"Project Name\"\r\n```\r\n\r\n### `agentik run`\r\n\r\nRun an agent loop with profiles and run metadata. (CONFIG is typically a YAML under `agents/`, e.g., `agents/research.yaml`.)\r\n\r\n```bash\r\nagentik run CONFIG \\\r\n -p \"Prompt text\" \\\r\n --model TEXT \\\r\n --temperature FLOAT \\\r\n --stream \\\r\n --dry-run \\\r\n --save-transcript PATH \\\r\n --profile [fast|thorough|deterministic|creative|cheap|dev|none] \\\r\n --tag TAG \\\r\n --note TEXT \\\r\n --run-id TEXT \\\r\n --obs-max-chars INT\r\n```\r\n\r\n### Keys\r\n\r\n```bash\r\nagentik keys set openrouter sk-or-... [--global|--local]\r\nagentik keys show\r\n```\r\n\r\n### Models\r\n\r\n```bash\r\nagentik models list [--filter TEXT] [--refresh]\r\n```\r\n\r\n### New (scaffolding)\r\n\r\n```bash\r\nagentik new agent NAME \\\r\n --template basic \\\r\n --tools \"t1,t2\" \\\r\n --memory json \\\r\n --memory-path ./memory/agent.json \\\r\n --to . \\\r\n --with-tests \\\r\n --force\r\n\r\nagentik new tool NAME \\\r\n --template python \\\r\n --to . \\\r\n --with-tests \\\r\n --force\r\n```\r\n\r\n### Templates\r\n\r\n```bash\r\nagentik template list\r\nagentik template apply kind/name --to . --force --name MyArtifact\r\nagentik template pull <git-or-zip-url> --to .\r\n```\r\n\r\n### Tools\r\n\r\n```bash\r\nagentik tools list\r\nagentik tools info NAME\r\nagentik tools run NAME --arg key=value --arg key2=value2 [--json]\r\n```\r\n\r\n### Validate\r\n\r\n```bash\r\nagentik validate file CONFIG.yaml \\\r\n --show-effective \\\r\n --model TEXT \\\r\n --temperature FLOAT \\\r\n --max-steps INT\r\n```\r\n\r\n### Batch\r\n\r\nProcess prompts from CSV or JSONL.\r\n\r\n```bash\r\nagentik batch run FILE \\\r\n --column prompt \\\r\n --out results.jsonl \\\r\n --model TEXT \\\r\n --temperature FLOAT\r\n```\r\n\r\n### Memory\r\n\r\n```bash\r\nagentik memory init --type json --path ./memory/agentik.json\r\nagentik memory recall --n 10 [--config CONFIG.yaml]\r\nagentik memory summarize --n 20 --max-chars 1200 [--config CONFIG.yaml]\r\nagentik memory clear [--config CONFIG.yaml]\r\nagentik memory path [--config CONFIG.yaml]\r\n```\r\n\r\n### Eval\r\n\r\nTiny harness to check expected substrings/regex.\r\n\r\n```bash\r\nagentik eval run FILE.jsonl --config CONFIG.yaml --out eval_results.jsonl\r\n```\r\n\r\n### Dev Watch (auto\u2011rerun)\r\n\r\nWatches files and re\u2011runs on change \u2014 great during development.\r\n\r\n```bash\r\nagentik dev watch CONFIG \\\r\n -p \"Prompt text\" \\\r\n --prompt-file PATH \\\r\n --path PATH \\ # repeatable (default .)\r\n --include GLOB \\ # repeatable (default python/yaml/md/templates/tools)\r\n --exclude GLOB \\ # repeatable\r\n --interval 0.6 \\\r\n --debounce 0.5 \\\r\n --clear/--no-clear \\\r\n --stream/--no-stream \\\r\n --profile dev \\\r\n --save-transcripts DIR \\\r\n --obs-max-chars 800 \\\r\n --no-initial-run \\\r\n --tag TAG \\ # repeatable (default \"dev\")\r\n --note TEXT\r\n```\r\n\r\nExample (PowerShell):\r\n\r\n```powershell\r\nagentik dev watch .\\agents\\agent.yaml `\r\n --prompt-file .\\prompt.txt `\r\n --path . `\r\n --include **/*.py --include **/*.yaml --include templates/** `\r\n --exclude .venv/** --exclude runs/** `\r\n --save-transcripts .\\runs `\r\n --stream\r\n```\r\n\r\n---\r\n\r\n## Tools & Policies\r\n\r\n**Built\u2011in tools (selected):**\r\n\r\n* `http_fetch(url, ttl, timeout, max_bytes, headers, allow_network)`\r\n Returns `{ok, data, error, meta}` with `data.text`, `data.status`, and cache hints.\r\n\r\n* `html_to_text(html, keep_newlines, drop_links, max_chars)`\r\n Lightweight HTML \u2192 text (dependency\u2011free).\r\n\r\n* `write_file(path, content, encoding, overwrite, allow_abs, allow_filesystem)`\r\n Safe writer with sandboxing and system\u2011path guards.\r\n\r\n**Policies (YAML):**\r\n\r\n```yaml\r\npolicies:\r\n allow_network: true\r\n allow_filesystem: false\r\n```\r\n\r\nIf a tool requires a disabled capability, Agentik blocks it and records an observation.\r\n\r\n---\r\n\r\n## Transcripts & Cost\r\n\r\nEach run can append JSONL records via `--save-transcript`. Files include:\r\n\r\n* `meta_start`: run id, profile, tags, agent, model, policies, memory path\r\n* Tool calls and assistant responses\r\n* `meta_end`: timings (planner/tools/reflect), tokens (prompt/completion/total), **estimated cost**\r\n\r\nCost is derived from OpenRouter pricing when available. You can override with env vars:\r\n\r\n```powershell\r\n# USD per 1K tokens\r\n$env:AGENTIK_PRICE_PROMPT_PER_1K = \"0.50\"\r\n$env:AGENTIK_PRICE_COMPLETION_PER_1K = \"1.50\"\r\n```\r\n\r\n---\r\n\r\n## Configuration Reference (YAML)\r\n\r\n```yaml\r\nagent:\r\n name: my-agent\r\n goal: \"Help with tasks.\"\r\n loop:\r\n max_steps: 4\r\n reflect: true\r\n\r\nllm:\r\n model: openai/gpt-4o-mini\r\n temperature: 0.2\r\n\r\nmemory:\r\n type: json # json | dict\r\n path: ./memory/agent.json\r\n\r\npolicies:\r\n allow_network: true\r\n allow_filesystem: false\r\n\r\ntools:\r\n - http_fetch\r\n - html_to_text\r\n```\r\n\r\n---\r\n\r\n---\r\n\r\n# Agentik CLI \u2014 All Command Reference\r\n\r\nA clean, practical guide to the `agentik` command\u2011line interface. Use this to initialize projects, scaffold agents/tools, run and iterate, manage config, and evaluate.\r\n\r\n**Typical workflow:** `init \u2192 new \u2192 run \u2192 dev`\r\n\r\n---\r\n\r\n## Table of Contents\r\n\r\n1. [Basic Information](#basic-information)\r\n2. [Project Setup](#project-setup)\r\n3. [Core Functionality](#core-functionality)\r\n4. [Configuration & Management](#configuration--management)\r\n5. [Data & Evaluation](#data--evaluation)\r\n\r\n---\r\n\r\n## Basic Information\r\n\r\nCommands that show tool and environment details.\r\n\r\n### `version`\r\n\r\nShows the installed version of the Agentik CLI.\r\n\r\n```bash\r\nagentik version\r\n```\r\n\r\n### `self-test`\r\n\r\nChecks whether your environment (Python/OS/API keys) is set up correctly.\r\n\r\n```bash\r\nagentik self-test\r\n```\r\n\r\n---\r\n\r\n## Project Setup\r\n\r\nCreate projects, agents, and tools from templates.\r\n\r\n### `init`\r\n\r\nInitialize a new project directory with the standard structure (`agents/`, `tools/`, etc.).\r\n\r\n**Example: Create a project in a folder named `my-first-project`.**\r\n\r\n```bash\r\nagentik init my-first-project\r\n```\r\n\r\n### `new`\r\n\r\nScaffold new files from templates.\r\n\r\n#### `new agent`\r\n\r\nCreate a new agent YAML configuration.\r\n\r\n**Example: Inside your project, create an agent named `researcher` that uses the `web_search` tool.**\r\n\r\n```bash\r\ncd my-first-project\r\nagentik new agent researcher --tools \"web_search\" --to ./agents\r\n```\r\n\r\n#### `new tool`\r\n\r\nCreate a new custom tool (Python file).\r\n\r\n**Example: Create a tool named `calculator` in `./tools`.**\r\n\r\n```bash\r\nagentik new tool calculator --to ./tools\r\n```\r\n\r\n### `template`\r\n\r\nManage built-in and third\u2011party templates.\r\n\r\n#### `template list`\r\n\r\nShow all available templates for projects, agents, and tools.\r\n\r\n```bash\r\nagentik template list\r\n```\r\n\r\n#### `template apply`\r\n\r\nApply a specific template to a directory.\r\n\r\n```bash\r\nagentik template apply agent/basic --to ./agents --name \"my-basic-agent\"\r\n```\r\n\r\n---\r\n\r\n## Core Functionality\r\n\r\nRun and iterate on your agents.\r\n\r\n### `run`\r\n\r\nRun an agent using a specific configuration file to complete a task.\r\n\r\n**Example: Run the `researcher` agent with a prompt and save the transcript.**\r\n\r\n```bash\r\nagentik run .\\agents\\researcher.yaml \\\r\n -p \"What is the current time in India?\" \\\r\n --save-transcript .\\runs\\research-run.jsonl\r\n```\r\n\r\n### `dev`\r\n\r\nWatch project files for changes and automatically re-run your agent for rapid iteration.\r\n\r\n**Example: Re-run the `researcher` agent whenever a `.py` or `.yaml` file is saved.**\r\n\r\n```bash\r\nagentik dev watch .\\agents\\researcher.yaml --prompt \"Summarize the agentik framework in 5 bullets.\"\r\n```\r\n\r\n> **Note:** If you encounter a `generator` error while streaming, add `--no-stream`.\r\n\r\n---\r\n\r\n## Configuration & Management\r\n\r\nManage API keys, models, tools, validation, and configuration paths.\r\n\r\n### `keys`\r\n\r\nStore and view API keys (e.g., OpenRouter) used by Agentik.\r\n\r\n**Set a key:**\r\n\r\n```bash\r\n# Replace with your actual key\r\nagentik keys set sk-or-xxxxxxxxxxxxxxxxxxxxxxxxxx\r\n```\r\n\r\n**Show the active key (from env and `.agentikrc`):**\r\n\r\n```bash\r\nagentik keys show\r\n```\r\n\r\n### `models`\r\n\r\nList available models (via OpenRouter) with optional filtering.\r\n\r\n**Example: List models containing \"claude\".**\r\n\r\n```bash\r\nagentik models list --filter \"claude\"\r\n```\r\n\r\n### `tools`\r\n\r\nDiscover and test tools locally.\r\n\r\n**List discovered tools:**\r\n\r\n```bash\r\nagentik tools list\r\n```\r\n\r\n**Run a specific tool with arguments (useful for testing):**\r\n\r\n```bash\r\nagentik tools run file_reader --arg \"path=./README.md\"\r\n```\r\n\r\n### `validate`\r\n\r\nValidate an agent YAML configuration file.\r\n\r\n```bash\r\nagentik validate file .\\agents\\researcher.yaml\r\n```\r\n\r\n### `config`\r\n\r\nLocate configuration file paths used by Agentik (`.agentikrc`).\r\n\r\n**Global config path:**\r\n\r\n```bash\r\nagentik config path --global\r\n```\r\n\r\n**Local project config path:**\r\n\r\n```bash\r\nagentik config path --local\r\n```\r\n\r\n---\r\n\r\n## Data & Evaluation\r\n\r\nWork with agent memory, batch processing, and test evaluations.\r\n\r\n### `memory`\r\n\r\nInteract with an agent\u2019s memory (requires a config file to target the correct memory store).\r\n\r\n**Recall the last N items:**\r\n\r\n```bash\r\nagentik memory recall --config .\\agents\\researcher.yaml --n 5\r\n```\r\n\r\n**Clear memory:**\r\n\r\n```bash\r\nagentik memory clear --config .\\agents\\researcher.yaml\r\n```\r\n\r\n### `batch`\r\n\r\nRun a set of prompts from a CSV or JSONL file through a specified model.\r\n\r\n**Example: Prepare `prompts.csv`**\r\n\r\n```text\r\nid,question\r\n1,\"What is 2+2?\"\r\n2,\"What is the capital of France?\"\r\n```\r\n\r\n**Run the batch (using the `question` column):**\r\n\r\n```bash\r\nagentik batch run prompts.csv --column \"question\" --out results.jsonl --model \"openai/gpt-4o-mini\"\r\n```\r\n\r\n### `eval`\r\n\r\nEvaluate an agent against test cases.\r\n\r\n**Example: Create `tests.jsonl`**\r\n\r\n```json\r\n{\"prompt\": \"What is the capital of Germany?\", \"expect_contains\": [\"Berlin\"]}\r\n{\"prompt\": \"Calculate 5*5.\", \"expect_regex\": \"25\"}\r\n```\r\n\r\n**Run the evaluation:**\r\n\r\n```bash\r\nagentik eval run tests.jsonl --config .\\agents\\researcher.yaml --out eval-results.jsonl\r\n```\r\n\r\n---\r\n\r\n### Quick Tips\r\n\r\n* Use `--no-stream` if your terminal shows streaming-related generator errors.\r\n* Keep agent configs small and composable; prefer separate YAMLs for different roles.\r\n* Commit `.agentikrc` cautiously; consider environment variables for secrets in CI/CD.\r\n\r\n---\r\n\r\n## Development\r\n\r\n* **Lint/format:** `ruff check .` and `black .`\r\n* **Tests:** `pytest -q`\r\n* **Build:** `python -m build`\r\n* **Publish:** `twine upload dist/*`\r\n\r\n---\r\n\r\n## Authors\r\n\r\n* Vinay Joshi \u2014 [joshivinay822@gmail.com](mailto:joshivinay822@gmail.com)\r\n* Avinash Raghuvanshi \u2014 [avi95461@gmail.com](mailto:avi95461@gmail.com)\r\n\r\n## License\r\n\r\n[MIT](LICENSE)\r\n\r\n---\r\n\r\n**Happy building with Agentik!**\r\n\r\n---\r\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Agentik \u2014 a CLI-first, modular agent framework that runs LLMs via OpenRouter.",
"version": "0.1.9",
"project_urls": null,
"split_keywords": [
"agents",
" cli",
" llm",
" openrouter",
" framework",
" automation"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a2edb87f6780bb9f150b71c9486fee05ea9d74d3e927eff70aec85b1b2f91183",
"md5": "cb17acfdce6ec274f7a3f0d0eb1d3e36",
"sha256": "96a3ea1a69decdbc2b2227869721f7fd8d5d96000ead09f2894f63dcaf6fd5da"
},
"downloads": -1,
"filename": "agentik_framework-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cb17acfdce6ec274f7a3f0d0eb1d3e36",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 51394,
"upload_time": "2025-08-12T16:02:15",
"upload_time_iso_8601": "2025-08-12T16:02:15.496622Z",
"url": "https://files.pythonhosted.org/packages/a2/ed/b87f6780bb9f150b71c9486fee05ea9d74d3e927eff70aec85b1b2f91183/agentik_framework-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "de3aa008b6d1eb8f35ee988b25e76f9059d2dbd5005eaf9f8e3d9ecbf5200399",
"md5": "b2182718bd18d77c996f679a8189ac97",
"sha256": "f215e4aeef9afba7694e026a874cec86e8f4cc6a3f2de121903558b0aba5315c"
},
"downloads": -1,
"filename": "agentik_framework-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "b2182718bd18d77c996f679a8189ac97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 49862,
"upload_time": "2025-08-12T16:02:17",
"upload_time_iso_8601": "2025-08-12T16:02:17.411805Z",
"url": "https://files.pythonhosted.org/packages/de/3a/a008b6d1eb8f35ee988b25e76f9059d2dbd5005eaf9f8e3d9ecbf5200399/agentik_framework-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-12 16:02:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "agentik-framework"
}
JSON